---
id: controller-typed-request-contracts
trigger: "when creating or modifying any Spring Controller in foodie_server"
confidence: 0.9
domain: "code-style"
source: "explicit-user-instruction"
---

# Use typed Controller request contracts

## Action

- Receive authentication tokens with the exact controller parameter form `@RequestHeader String token`.
- Do not use `HttpServletRequest` to read tokens or inject it only for token access.
- For POST handlers that receive business input, use an explicit DTO and annotate it with `@RequestBody`; do not rely on implicit binding.
- For GET handlers, annotate every query parameter explicitly with `@RequestParam`. Continue to use `@RequestHeader` for tokens and `@PathVariable` for URL path variables.
- Never use `Map<String, String>` or another Map as a handler-method input.
- Bind third-party form callbacks to DTOs; convert a DTO to an internal Map only when a signature or gateway SDK requires it.

## Evidence

- The user explicitly established this as a permanent rule for all controllers on 2026-08-10.
- `PosOrderController` demonstrates the required forms with `@RequestBody OrderDTO` on POST handlers and explicit `@RequestParam` annotations on GET query parameters.
