Nhận tham số: @PathVariable, @RequestParam, @RequestBody và các bạn

Câu này nền tảng nhưng phỏng vấn hay hỏi kèm bẫy: "thiếu param thì sao?", "gửi chữ vào chỗ số thì trả gì?". Mình đi lần lượt trên OrderController.

1. Bài toán: 4 endpoint của OrderController

POST   /api/orders                         body JSON  → tạo order
GET    /api/orders?status=PAID&page=0&size=20      → list, có filter
GET    /api/orders/42                                 → chi tiết
POST   /api/orders/42/cancel   header X-Request-Id    → hủy

Dữ liệu nằm ở 4 chỗ khác nhau trong HTTP request: path, query string, body, header. Mỗi chỗ có một annotation.

2. Vấn đề

• Nếu tự đọc HttpServletRequest.getParameter("page") rồi Integer.parseInt, code lặp ở mọi method, quên check null, parse lỗi ném NumberFormatException → client nhận 500 thay vì 400.
• Filter có 6–7 field (status, from, to, customerId, minTotal…) mà khai báo từng @RequestParam thì method signature dài cả màn hình.

3. Giải pháp: mỗi nguồn dữ liệu một annotation

Tất cả đều do các HandlerMethodArgumentResolver xử lý trước khi method controller được gọi (luồng tổng ở bài 4.2.2).

4. Code từng bước

Bước 1: dependency. Chỉ cần spring-boot-starter-web. Pageable cần thêm spring-boot-starter-data-jpa (Spring Data Web support tự bật).

Bước 2: config giới hạn page size để client không xin size=100000:

spring:
  data:
    web:
      pageable:
        default-page-size: 20
        max-page-size: 100

Bước 3: code Java.

public record OrderFilter(
        OrderStatus status,                 // enum: "PAID" → OrderStatus.PAID
        Long customerId,
        @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate from,
        @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate to) {}

public record CreateOrderRequest(Long customerId, List<OrderLineRequest> lines) {}

@RestController
@RequestMapping("/api/orders")
@RequiredArgsConstructor
public class OrderController {
    private final OrderService orderService;

    @PostMapping
    public OrderResponse create(@RequestBody CreateOrderRequest req) {
        return orderService.create(req);
    }

    @GetMapping
    public Page<OrderResponse> list(OrderFilter filter,          // @ModelAttribute ngầm định
                                    @PageableDefault(sort = "createdAt",
                                        direction = Sort.Direction.DESC) Pageable pageable) {
        return orderService.search(filter, pageable);
    }

    @GetMapping("/{id}")
    public OrderResponse get(@PathVariable Long id) {
        return orderService.get(id);
    }

    @PostMapping("/{id}/cancel")
    public OrderResponse cancel(@PathVariable Long id,
                                @RequestParam(defaultValue = "CUSTOMER_REQUEST") CancelReason reason,
                                @RequestHeader(name = "X-Request-Id", required = false) String requestId) {
        return orderService.cancel(id, reason, requestId);
    }
}

Lưu ý: Spring Boot 3 (Spring 6.1+) không còn tự đọc tên tham số từ debug info. Phải build với -parameters (Spring Boot plugin Maven/Gradle đã bật sẵn), nếu không thì phải ghi @PathVariable("id").

Bước 4: test bằng curl.

curl -s localhost:8080/api/orders/42
curl -s "localhost:8080/api/orders?status=PAID&from=2026-10-01&page=0&size=5&sort=total,desc"
curl -s -X POST localhost:8080/api/orders -H 'Content-Type: application/json' \
     -d '{"customerId":7,"lines":[{"productId":1,"quantity":2}]}'

# Gửi sai kiểu
curl -i localhost:8080/api/orders/abc          # → 400 (MethodArgumentTypeMismatchException)
curl -i "localhost:8080/api/orders?status=XYZ" # → 400 (binding error trên OrderFilter)
curl -i -X POST localhost:8080/api/orders -H 'Content-Type: application/json' -d '{bad'
                                               # → 400 (HttpMessageNotReadableException)

5. Cách hoạt động

HTTP request
   │
DispatcherServlet → HandlerAdapter (RequestMappingHandlerAdapter)
   │   với từng tham số của method:
   │     tìm HandlerMethodArgumentResolver hỗ trợ
   ├─ @PathVariable  → lấy "42" từ URI template → ConversionService → Long 42
   ├─ @RequestParam  → request.getParameter    → ConversionService → enum
   ├─ OrderFilter    → ServletModelAttributeMethodProcessor → WebDataBinder
   │                    (constructor record / setter, gom lỗi vào BindingResult)
   ├─ Pageable       → PageableHandlerMethodArgumentResolver
   ├─ @RequestBody   → RequestResponseBodyMethodProcessor → Jackson đọc body
   └─ @RequestHeader → header map → ConversionService
   │
   ├─ chuyển đổi lỗi? → exception → DefaultHandlerExceptionResolver → 400
   ▼
orderController.list(filter, pageable)

6. So sánh lỗi khi tham số sai

Format body lỗi cho đẹp và thống nhất là việc của bài 4.2.7.

7. Khi nào dùng cái nào

• @PathVariable: định danh resource (/orders/{id}). Thiếu nó thì URL không match → 404, không phải 400.
• @RequestParam: 1–3 tham số tùy chọn, filter đơn giản. Dùng defaultValue (tự hiểu là required=false) hoặc Optional<T>.
• @ModelAttribute / object filter: từ 3–4 filter trở lên, dễ thêm validation.
• @RequestBody: dữ liệu tạo/sửa. Không dùng cho GET.
• @RequestHeader: metadata (request id, idempotency key, tenant), không phải dữ liệu nghiệp vụ.

Đúng rồi, đó là bẫy kinh điển. Không gửi param thì giá trị là null, mà int primitive không nhận null → IllegalStateException → 500.

// Sai: thiếu param → null → không gán được vào int
@RequestParam(required = false) int page

// Đúng, chọn 1 trong 3
@RequestParam(defaultValue = "0") int page
@RequestParam(required = false) Integer page          // tự xử lý null
@RequestParam Optional<Integer> page

Một điểm nữa: defaultValue là String, được convert như giá trị client gửi. Gửi ?page= (rỗng) cũng rơi về default.

Bạn hiểu gần đúng, chỉ cần chỉnh một điểm: không có annotation thì Spring áp quy tắc mặc định, và mặc định không bao giờ là @RequestBody.

• Kiểu "simple" (String, số, enum, Date…) không annotation → coi như @RequestParam(required=false).
• Kiểu phức tạp (record, POJO) không annotation → coi như @ModelAttribute: bind từ query string/form theo tên field.
• @RequestBody luôn phải ghi rõ.

Hệ quả hay gặp: quên @RequestBody ở POST → Spring bind từ query string (rỗng) → object toàn null, không có lỗi gì. Thấy DTO toàn null thì kiểm tra cái này đầu tiên.

Không chặn. Pageable chỉ parse chuỗi. Sort theo field không tồn tại sẽ ném PropertyReferenceException khi query; sort theo field tồn tại nhưng nhạy cảm hoặc không index thì chạy thật. Nên whitelist:

private static final Set<String> SORTABLE = Set.of("createdAt", "total", "status");

static Pageable sanitize(Pageable p) {
    for (Sort.Order o : p.getSort()) {
        if (!SORTABLE.contains(o.getProperty())) {
            throw new BadRequestException("Cannot sort by " + o.getProperty());
        }
    }
    return p;
}

Chi tiết phân trang phía JPA (count query, keyset) ở bài 4.3.9. Và nhớ max-page-size ở bước 2.

Q1. Phân biệt @PathVariable, @RequestParam, @RequestBody?

🇻🇳 Tiếng Việt:

@PathVariable lấy giá trị từ đường dẫn, dùng để định danh resource như /orders/42. @RequestParam lấy từ query string hoặc form, hợp với filter và tham số tùy chọn. @RequestBody đọc body của request, thường là JSON, qua HttpMessageConverter để thành object, dùng cho dữ liệu tạo hoặc sửa. Hai cái đầu dùng ConversionService, cái cuối dùng Jackson.

🇬🇧 English:

@PathVariable reads a value from the URI path and identifies a resource, like /orders/42. @RequestParam reads from the query string or form data and fits filters and optional parameters. @RequestBody reads the request body, usually JSON, through an HttpMessageConverter into an object, for create or update payloads. The first two use the ConversionService, the last one uses Jackson.

Q2. Client gửi sai kiểu tham số thì Spring trả gì?

🇻🇳 Tiếng Việt:

Spring ném exception chuyển đổi như MethodArgumentTypeMismatchException, MissingServletRequestParameterException hoặc HttpMessageNotReadableException, và DefaultHandlerExceptionResolver map chúng thành 400. Em thêm @RestControllerAdvice để trả body lỗi thống nhất, nói rõ field nào sai. Bẫy cần tránh là tự parse bằng Integer.parseInt rồi để lọt NumberFormatException thành 500.

🇬🇧 English:

Spring throws conversion exceptions such as MethodArgumentTypeMismatchException, MissingServletRequestParameterException or HttpMessageNotReadableException, and the DefaultHandlerExceptionResolver maps them to 400. I add a @RestControllerAdvice to return a consistent error body that names the invalid field. The trap is parsing manually with Integer.parseInt and letting a NumberFormatException leak out as a 500.

Q3. Filter có nhiều tham số thì thiết kế thế nào?

🇻🇳 Tiếng Việt:

Em gom vào một record filter và để Spring bind như @ModelAttribute, kèm Pageable cho page, size, sort. Em giới hạn max page size và whitelist các field được sort để tránh query nặng hoặc lộ dữ liệu.

🇬🇧 English:

I group them into a filter record bound as a @ModelAttribute, plus a Pageable for page, size and sort. I cap the maximum page size and whitelist sortable fields to avoid heavy queries or data exposure.

Cách nhớ ngắn gọn

• Path → @PathVariable, query → @RequestParam, body → @RequestBody, header → @RequestHeader.
• Nhiều query param → record + @ModelAttribute (ngầm định). @RequestBody luôn phải ghi rõ.
• Optional: defaultValue, wrapper type, Optional. Không required=false với primitive.
• Sai kiểu/thiếu → 400 do Spring; tự parse thì dễ thành 500.