Controller Details: Argument Binding, Return Values and Conversion

The most common controller mistake is not syntax — it is not knowing where data can come from. A single @GetMapping method can accept a bewildering variety of parameters: query strings, path placeholders, request bodies, headers, cookies, sessions, raw streams. Each one is assembled by a different HandlerMethodArgumentResolver. Map the space of possibilities first with one table, then drill into the details — far more effective than memorizing APIs piecemeal.

How much of that table you can actually use is decided before any annotation, in pom.xml. Tick it yourself and it becomes obvious: with only web checked, @RequestBody works immediately while @Valid does nothing at all — validation was never part of MVC. And whether a @ModelAttribute object can bind at all depends on it having getters and setters, which is exactly what the lombok line buys you:

Writing {orderId:\\d+} attaches a regex constraint to that placeholder: only pure digits match. /orders/abc fails \d+, never reaches this mapping, and returns 404 — much cleaner than letting parsing fail inside the method.

@RequestBody relies on HttpMessageConverter (in JSON scenarios, MappingJackson2HttpMessageConverter). It inspects Content-Type first: not application/json means 415; JSON but structurally wrong (bad field type, missing required member) throws HttpMessageNotReadableException, which a global handler usually maps to 400.

@ModelAttribute writes each query-string (or form) entry into the object by property name, leaving absent fields at their defaults. It makes "a pile of filter parameters" look like one ordinary method parameter — the first choice for conditional-filter endpoints.

Dates are the classic "type mismatch scene": without a format hint, Spring cannot parse 2024-05-01 and returns 400. Enums are easier — they match names via Enum.valueOf by default, and a name that does not exist fails.

Every "String → target type" step above is governed by one component: ConversionService. It is Spring's general-purpose conversion facade, and both Converter and Formatter register with it.

These are parameter-level conversion declarations, scoped to the annotated field, with no global registration needed:

When a parameter is not a primitive but a value object of your own (say an OrderNo), you need a custom converter:

Both Converter and Formatter register via WebMvcConfigurer#addFormatters (annotating with @Component also gets them collected automatically):

With inputs covered, look at the other end. What a handler returns decides how Spring treats it:

The right way to read that table is not to memorize "which type pairs with which handler" but to understand the voting order: the handler table asks exactly one question, and that question is not about the return type. Tap through it:

That fork has a real scene you can click. The same return statement, only the class-level annotation swapped, and the exit changes entirely:

Finally, the six exits as one animation — frames ③ and ④ are the same method body living two different lives:

When you need precise control over status and headers, use ResponseEntity:

The fluent API reads like a sentence: .created(uri) = 201, .noContent() = 204, .ok() = 200. Whenever the status is not 200, or extra headers are needed, reach for ResponseEntity — it is clearer than calling setStatus by hand.

Every backend meets these two, yet their root causes differ completely:

When there are few parameters, each independent, each needing its own default, individual @RequestParam bindings are the most readable.

Once filter fields exceed five or six, individual bindings explode the signature and repeat required = false everywhere. Bundle them into an object and bind with @ModelAttribute — both the signature and validation become easier to maintain.

• Confusing @RequestParam with @PathVariable of the same name: /users/{id} with @RequestParam Long id will never get a value, because id lives in the path, not the query string. On a 400, first confirm which route this parameter actually takes
• Sending an object over GET with @RequestBody: GET typically has no body, so @RequestBody gives a 415 or reads an empty body. Use @ModelAttribute for compound GET filters
• @RequestBody can be read only once: underneath sits HttpServletRequest.getInputStream(), and a stream is consumed once. If an interceptor reads the body, a later @RequestBody throws HttpMessageNotReadableException (Stream closed / read end). To read it more than once, wrap it in a repeatable ContentCachingRequestWrapper

All three traps above live in your code. A fourth one does not — it lives in a server property: the size ceiling for application/x-www-form-urlencoded POST bodies. Cross it and Tomcat simply stops parsing form parameters, so your @RequestParam behaves as though the client sent nothing and reports a 400. Drag the number and watch the four shapes this failure takes:

The first eight sections covered what you can write. This one steps back to why it is shaped this way — because a picture beats a list of rules.

On the other side of the glass there is a second rule: the shape of what you hand out decides how it gets packed. Return an object = packed as a JSON parcel and shipped; return a String = read as "which room to collect your item from", i.e. a view name. That fork is the entire origin of the trap in Section 4.

After this article you should answer:

• "Do the 1 in ?page=1 and the 42 in /users/42 travel the same road?" (No: query string versus path placeholder, two different resolvers)
• "Why does the same string sometimes become a Long and sometimes a 400?" (Depends whether a format hint and a converter exist)
• "Why should a GET endpoint not use @RequestBody?" (Semantically a query should carry no body; practically you throw away the ability to open the URL in a browser)

Section 2 said "resolvers are tried in order" — worth verifying with your own hands. The chain has this shape:

Note the last box: when no resolver claims the parameter you get IllegalStateException (a 500), not a 400. "I do not know where to fetch your value" and "I fetched it but it is wrong" are two entirely different failures — the first means your signature is broken, the second means the caller's payload is. The demo below turns all five cases into switchable scenes:

Once you can see the shape, you also need to know what it looks like in code. The seven lines on the left are the skeleton of getMethodArgumentValues; variables and the call stack refresh on the right. Press next and watch two things: args[i] and the UNRESOLVED sentinel:

Pull the lens back one notch: once the chain finishes, how did the request even reach this method? That is doDispatch from #22. The same method seen at two scales tells one story; switch to /nope and you will see "it never even got to argument resolution":

Finally the road after the value is fetched — conversion. "2024-05-01" becoming a LocalDate is not magic; there is a fixed lookup order: built-in converters first, then format annotations on the field, then the Converter you registered yourself.

When this chain fails, the exception resolver takes over and translates it into a status code. Switch to the "conversion failure" scene and you will see the Section 3 ConversionService error landing on a 400 — which explains why "the same bad input prints different words":

The reverse leg of the same road exists too: how the object you return turns back into text. That is owned by content negotiation plus message converters, and its four scenes cover exactly the String ambiguity of Section 4 — in the string scene you watch one and the same "success" split into two fates depending on whether @ResponseBody is present, and the fail scene is the live version of the No converter for ... with preset Content-Type row in Section 11's table:

When the clicking is done, switch to a command line. This console is wired to the same kernel in your browser and every reply is computed — run boot, then type the four parameter sources one by one. The last two are the failure demos:

One row in that table is special: Could not resolve parameter [0] is the only 500 caused by your own signature. Here is that stack for real — do not read the analysis first; click the line you believe is guilty:

The same signature behaves completely differently depending on how @RequestParam's three attributes are combined. Pick a pair and the output is the endpoint's real behaviour.

Goal: one endpoint that consumes all four input sources at once, and verify where each one actually comes from.

Five curls covering four sources and two failures:

Expected response for command 1:

Expected response for command 5 (size kept its field default of 20):

Each edit is one or two lines; the point is to watch the error sentence swap:

1. Change @PathVariable Long id to @RequestParam Long id and rerun command 1 → you observe a 400 whose exception is now Required request parameter 'id' ... is not present: the trap from Section 12's first question, made real
2. Replace @RequestBody SearchForm form with @ModelAttribute SearchForm form and send curl -X POST .../search?keyword=phone&from=2024-05-01 → you observe a 200: the same data may arrive via the query string, provided you swapped the pickup slip
3. Add @Valid to the parameter (@Valid @RequestBody SearchForm form) while SearchForm keeps @NotBlank String keyword, then send {"keyword":""} → you observe a 400 with MethodArgumentNotValidException naming the field keyword. Without @Valid the exact same request sails through with a 200 — that is the division of labour between "switch" and "constraint"
4. Change the from field type from LocalDate to String and rerun command 4 → you observe a 200: the error did not disappear, you merely postponed it into business code. Section 11's table calls this principle "let the framework fail early"

Build a "filter receiver": a list endpoint with a dozen filter fields that stays clean, readable, validatable and extensible.

Requirements:

• An OrderQuery object holding status (enum), from/to (LocalDate with @DateTimeFormat), minAmount (BigDecimal with @NumberFormat(pattern = "#,###.##")), keyword, page, size
• A custom Converter<String, OrderStatus> so clients may send lowercase active and still bind to ACTIVE
• A @RestControllerAdvice mapping MethodArgumentTypeMismatchException and MissingServletRequestParameterException each to a unified 400 body carrying a code
• Two variants of the same filter: one @ModelAttribute (GET) and one @RequestBody (POST search), proving both slips deliver identical values

Acceptance checklist:

• [ ] ?status=active&page=2&minAmount=12,345.67 binds completely (print the object and verify)
• [ ] ?from=2024-13-01 returns 400 and the body reveals which field broke — not a bare Whitelabel page
• [ ] ?size= (empty) does not explode, and you can explain why it is not "absent" — compare the empty|plain cell of Section 13's sandbox
• [ ] The GET variant works without a body; swapping @ModelAttribute for @RequestBody makes the same GET fail instantly, and you can name both the status code and the fully-qualified exception
• [ ] Adding one more filter changes only OrderQuery — not a single line of the method signature