ResponseEntity & HTTP status — trả response đúng ngữ nghĩa REST

TL;DR: Spring MVC có 3 cách trả response — return DTO trực tiếp (default 200 OK), ResponseEntity builder (custom status + header + body), và @ResponseStatus trên method. HTTP status code có ngữ nghĩa cụ thể theo từng nhóm: POST tạo resource mới nên trả 201 Created với Location header, DELETE trả 204 No Content, async operation trả 202 Accepted. ResponseEntity.created(uri).body(dto) là pattern chuẩn cho POST. Bên dưới, Spring dùng HttpMessageConverter — cụ thể là MappingJackson2HttpMessageConverter — để serialize Java object thành JSON bytes. Status code sai = phá REST contract với client.

Bài ArgumentResolver đã bóc cách Spring bind request vào tham số method. Bài này đi chiều ngược lại: khi controller return orderDto, Spring chọn status code nào? Header gì? Serialize body ra sao? Khi nào cần ResponseEntity thay vì return DTO trực tiếp?

1. Ba cách trả response

Spring MVC hỗ trợ 3 cách đặt response từ handler method, mỗi cách phù hợp một use case khác nhau.

1.1 Return DTO trực tiếp — default 200 OK

@GetMapping("/orders/{id}")
public OrderDto get(@PathVariable Long id) {
    return orderService.findById(id);
    // Spring tu dong: status 200, body = JSON cua OrderDto
}

Đây là cách đơn giản nhất. Spring đặt status 200 OK mặc định và uỷ cho HttpMessageConverter serialize return value thành JSON. Không cần viết thêm gì khi endpoint luôn thành công và trả đúng 200.

1.2 ResponseEntity — kiểm soát hoàn toàn

@PostMapping("/orders")
public ResponseEntity<OrderDto> create(@Valid @RequestBody OrderRequest req) {
    OrderDto created = orderService.create(req);
    URI location = ServletUriComponentsBuilder.fromCurrentRequest()
        .path("/{id}").buildAndExpand(created.id()).toUri();
    return ResponseEntity.created(location).body(created);
    // 201 Created + Location header + body
}

ResponseEntity<T> là wrapper giữ ba thứ cùng nhau: status code, headers, và body. Dùng khi cần status khác 200, custom header, hoặc body tuỳ điều kiện (có thể 200 hoặc 404 tuỳ logic).

1.3 @ResponseStatus — khai báo tĩnh

@DeleteMapping("/orders/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void delete(@PathVariable Long id) {
    orderService.delete(id);
    // 204 No Content, no body
}

@ResponseStatus khai báo status code cố định cho method, không cần bọc ResponseEntity. Phù hợp khi status luôn giống nhau và không cần custom header.

Bảng so sánh:

2. HTTP status code — ngữ nghĩa 4 nhóm

HTTP status code (RFC 9110) không phải số tùy ý — chúng chia thành 4 nhóm với ngữ nghĩa riêng biệt. Chọn sai nhóm là phá vỡ REST contract: client không biết request thành công hay thất bại mà không parse body.

flowchart LR
  subgraph G2["2xx -- Thanh cong"]
    direction TB
    A1["200 OK<br/>GET/PUT co body"]
    A2["201 Created<br/>POST tao moi + Location"]
    A3["202 Accepted<br/>async, chua hoan thanh"]
    A4["204 No Content<br/>DELETE, khong body"]
  end
  subgraph G3["3xx -- Chuyen huong"]
    direction TB
    B1["301 Moved Permanently"]
    B2["304 Not Modified<br/>cache hit, no body"]
  end
  subgraph G4["4xx -- Loi client"]
    direction TB
    C1["400 Bad Request<br/>validation fail"]
    C2["401 Unauthorized<br/>chua xac thuc"]
    C3["403 Forbidden<br/>khong quyen"]
    C4["404 Not Found"]
    C5["409 Conflict<br/>duplicate/state"]
    C6["429 Too Many Requests"]
  end
  subgraph G5["5xx -- Loi server"]
    direction TB
    D1["500 Internal Server Error"]
    D2["502 Bad Gateway"]
    D3["503 Service Unavailable"]
  end

2.1 2xx — Thành công

200 OK là default khi return DTO trực tiếp. Nhưng POST tạo resource mới phải dùng 201 Created:

// Dung -- POST tra 201 Created
@PostMapping("/orders")
public ResponseEntity<OrderDto> create(@Valid @RequestBody OrderRequest req) {
    OrderDto created = orderService.create(req);
    URI location = ServletUriComponentsBuilder.fromCurrentRequest()
        .path("/{id}").buildAndExpand(created.id()).toUri();
    return ResponseEntity.created(location).body(created);
}
// Response headers:
//   HTTP/1.1 201 Created
//   Location: /api/orders/42

Vì sao 201 + Location quan trọng hơn 200? Vì nó nói cho client biết resource mới nằm ở đâu mà không cần client tự suy URL. Frontend có thể dùng Location header để redirect hoặc refetch mà không hard-code URL pattern.

204 No Content cho DELETE — action thành công nhưng không có gì để trả:

@DeleteMapping("/orders/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void delete(@PathVariable Long id) {
    orderService.delete(id);
}
// HTTP/1.1 204 No Content (no body)

202 Accepted khi operation được nhận nhưng chưa hoàn thành — ví dụ async export job:

@PostMapping("/orders/{id}/export")
public ResponseEntity<Void> exportAsync(@PathVariable Long id) {
    String jobId = exportService.startExportJob(id);
    return ResponseEntity.accepted()
        .header("X-Job-Id", jobId)
        .build();
}
// HTTP/1.1 202 Accepted
// X-Job-Id: job-abc123

202 nói với client: "Tôi đã nhận yêu cầu, đang xử lý — poll GET /jobs/{jobId} sau để biết kết quả." Pattern này tránh timeout cho operation chạy vài phút.

2.2 3xx — Chuyển hướng

REST API hiếm dùng 3xx, ngoại trừ 304 Not Modified cho conditional GET:

@GetMapping("/orders/{id}")
public ResponseEntity<OrderDto> get(
    @PathVariable Long id,
    @RequestHeader(value = "If-None-Match", required = false) String ifNoneMatch
) {
    OrderDto order = orderService.findById(id);
    String etag = "\"" + order.version() + "\"";
    if (etag.equals(ifNoneMatch)) {
        return ResponseEntity.status(HttpStatus.NOT_MODIFIED).build();
    }
    return ResponseEntity.ok().eTag(etag).body(order);
}

Client gửi If-None-Match: "v3" — nếu version chưa đổi, server trả 304 không có body, tiết kiệm bandwidth.

2.3 4xx — Lỗi do client

4xx nghĩa là client gửi sai — request thiếu thông tin, sai định dạng, hoặc không có quyền. Server không sai.

Pitfall quan trọng nhất: không bao giờ trả 200 với body {"error": "..."} cho client error. Client dựa vào status code để quyết định xử lý UI — nếu status luôn 200, client phải parse body mới biết thất bại hay không. Đây là vi phạm REST contract.

2.4 5xx — Lỗi server

5xx nghĩa là server sai — client gửi đúng nhưng server không xử lý được.

5xx không bao giờ được trả cho request client gửi sai — đó là 4xx.

3. ResponseEntity builder — API đầy đủ

ResponseEntity dùng builder pattern — chain method để set từng phần response:

// Static factory nhanh
ResponseEntity.ok(body)                        // 200 + body
ResponseEntity.ok()                            // 200 builder, chain header roi .body(dto)
ResponseEntity.created(uri)                    // 201 + Location header tu uri
ResponseEntity.accepted()                      // 202
ResponseEntity.noContent()                     // 204 builder
ResponseEntity.notFound()                      // 404 builder
ResponseEntity.badRequest()                    // 400 builder
ResponseEntity.status(HttpStatus.CONFLICT)     // bat ky status tuy chinh

// Chain header + body
return ResponseEntity.ok()
    .header("X-Total-Count", String.valueOf(total))
    .header("X-Request-Id", requestId)
    .lastModified(order.updatedAt())
    .body(orders);

Generic type parameter:

ResponseEntity<OrderDto>    // body kieu OrderDto
ResponseEntity<List<OrderDto>>
ResponseEntity<Void>        // khong co body (DELETE, 202)
ResponseEntity<?>           // kieu dong (su dung han che -- mat type safety)

ResponseEntity<Void> dùng cho response không body — phân biệt rõ ràng với ResponseEntity<OrderDto> trả về null body.

Pattern conditional response — cùng method có thể trả 200 hoặc 404:

@GetMapping("/orders/{id}")
public ResponseEntity<OrderDto> get(@PathVariable Long id) {
    return orderService.findOptional(id)
        .map(ResponseEntity::ok)
        .orElseGet(() -> ResponseEntity.notFound().build());
}

Method return type ResponseEntity<OrderDto> nên compiler kiểm tra được kiểu body.

4. Cơ chế bên dưới — HttpMessageConverter serialize

Khi Spring nhận return value từ handler method, nó không tự biết "phải ghi gì vào response". Cơ chế chịu trách nhiệm là HttpMessageConverter — interface quyết định serialize Java object thành bytes và ngược lại.

flowchart TB
  A["Controller<br/>return OrderDto hoac ResponseEntity"] --> B["HandlerMethodReturnValueHandler<br/>xu ly return value"]
  B --> C{"Content negotiation<br/>Accept header tu client?"}
  C -->|"Accept: application/json"| D["MappingJackson2HttpMessageConverter<br/>Jackson serialize -> JSON bytes"]
  C -->|"Accept: application/xml"| E["Jaxb2RootElementHttpMessageConverter<br/>JAXB serialize -> XML bytes"]
  C -->|"Khong converter nao khop"| F["406 Not Acceptable"]
  D --> G["HttpServletResponse<br/>status + headers + body bytes"]
  E --> G
  B -->|"ResponseEntity"| H["Lay status + headers tu ResponseEntity<br/>roi dua body qua converter"]
  H --> D

Luồng cụ thể khi return orderDto:

1. DispatcherServlet gọi HandlerMethodReturnValueHandler xử lý return value.
2. Handler xem Accept header từ client (application/json là default của hầu hết REST client).
3. Tìm HttpMessageConverter nào hỗ trợ kiểu Java (OrderDto) và MediaType (application/json).
4. MappingJackson2HttpMessageConverter (Jackson 2) được chọn — gọi ObjectMapper.writeValue() serialize OrderDto thành JSON bytes.
5. Spring ghi bytes vào HttpServletResponse.getOutputStream(), set Content-Type: application/json.

Khi return ResponseEntity, Spring trước tiên lấy status code và headers từ ResponseEntity, sau đó đưa body qua cùng pipeline converter trên.

Vì sao quan trọng: nếu Jackson không tìm thấy getter cho một field (ví dụ thiếu @JsonProperty), field đó không xuất hiện trong JSON — không có lỗi compile, chỉ là JSON bị thiếu field. Hiểu converter pipeline giúp debug loại bug này.

Content negotiation — Spring chọn converter dựa trên Accept header. Nếu client gửi Accept: application/xml nhưng không có Jackson XML hay JAXB trên classpath, Spring trả 406 Not Acceptable. Đây là tính năng, không phải bug: client khai báo muốn format gì, server chọn converter phù hợp.

5. Header phổ biến trong REST response

ResponseEntity cho phép set bất kỳ header nào. Các header có ngữ nghĩa quan trọng:

// Pagination response voi header
@GetMapping
public ResponseEntity<List<OrderDto>> list(Pageable pageable) {
    Page<OrderDto> page = orderService.list(pageable);
    return ResponseEntity.ok()
        .header("X-Total-Count", String.valueOf(page.getTotalElements()))
        .header("X-Total-Pages", String.valueOf(page.getTotalPages()))
        .header("X-Page-Number", String.valueOf(page.getNumber()))
        .body(page.getContent());
}

6. Pitfall — những lỗi hay gặp

Pitfall 1 — POST trả 200 thay 201:

// SAI: POST tao moi nhung tra 200, khong co Location
@PostMapping("/orders")
public OrderDto create(@Valid @RequestBody OrderRequest req) {
    return orderService.create(req);
}

// DUNG: 201 Created + Location header
@PostMapping("/orders")
public ResponseEntity<OrderDto> create(@Valid @RequestBody OrderRequest req) {
    OrderDto created = orderService.create(req);
    URI location = ServletUriComponentsBuilder.fromCurrentRequest()
        .path("/{id}").buildAndExpand(created.id()).toUri();
    return ResponseEntity.created(location).body(created);
}

Client (đặc biệt là API gateway hoặc SDK tự động) dùng Location header để biết URL resource vừa tạo. Thiếu Location là bỏ qua một phần của HTTP 201 spec (RFC 9110 §15.3.2).

Pitfall 2 — DELETE trả 200 với body null:

// SAI: void method, Spring gui 200 + body rong -- client confused
@DeleteMapping("/orders/{id}")
public void delete(@PathVariable Long id) {
    orderService.delete(id);
}

// DUNG: 204 No Content, ro rang khong co body
@DeleteMapping("/orders/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void delete(@PathVariable Long id) {
    orderService.delete(id);
}

Pitfall 3 — Trả 200 với body error cho 4xx:

// SAI: 200 OK nhung body bao loi -- pha REST contract
@GetMapping("/orders/{id}")
public Map<String, Object> get(@PathVariable Long id) {
    if (!orderService.exists(id)) {
        return Map.of("error", "not found");    // 200 voi body loi!
    }
    return Map.of("data", orderService.findById(id));
}

// DUNG: 404 ro rang
@GetMapping("/orders/{id}")
public ResponseEntity<OrderDto> get(@PathVariable Long id) {
    return orderService.findOptional(id)
        .map(ResponseEntity::ok)
        .orElseGet(() -> ResponseEntity.notFound().build());
}

Frontend và mobile client đọc status code trước khi quyết định parse body. Nếu status luôn 200, client phải parse body để biết lỗi — vừa phức tạp vừa không nhất quán với các API khác.

Pitfall 4 — Dùng ResponseEntity khi không cần:

// THUA: chi GET don gian ma dung ResponseEntity
@GetMapping("/orders")
public ResponseEntity<List<OrderDto>> list() {
    return ResponseEntity.ok(orderService.findAll());
}

// GIN GON: khi khong can custom gi
@GetMapping("/orders")
public List<OrderDto> list() {
    return orderService.findAll();
}

Chỉ dùng ResponseEntity khi thực sự cần custom status code, header, hoặc body điều kiện.

Liên hệ các bài khác

• Bài 02 — ArgumentResolver: chiều ngược lại — Spring bind request (path variable, request body, header) vào tham số method. Hiểu cả hai chiều (argument resolution + return value handling) mới thấy toàn bộ request-response lifecycle trong DispatcherServlet.
• Bài 04 — Response advanced: đào sâu ResponseBodyAdvice (global response wrapping), StreamingResponseBody (export file lớn không OOM), SseEmitter (real-time push), và HATEOAS link relation — những pattern build trên nền ResponseEntity bài này đặt ra.
• Bài 05 — Exception handling: khi service throw exception, @ExceptionHandler + @ControllerAdvice map exception thành 4xx/5xx response chuẩn RFC 9457 Problem Details — cơ chế hoàn thiện bức tranh status code bài này bắt đầu.

Tóm tắt

• Spring có 3 cách trả response: return DTO trực tiếp (200 OK mặc định), ResponseEntity (custom status + header + body), @ResponseStatus (status cố định trên method).
• HTTP status code có ngữ nghĩa: POST mới → 201 Created + Location; DELETE → 204 No Content; async → 202 Accepted; 4xx client sai; 5xx server sai. Không bao giờ trả 200 cho error case.
• ResponseEntity builder: chain .ok(), .created(uri), .accepted(), .noContent(), .notFound(), .status(...), .header(key, value), .body(dto).
• HttpMessageConverter — cụ thể MappingJackson2HttpMessageConverter — serialize Java object thành JSON bytes dựa trên Accept header. Đây là cơ chế bên dưới mọi return dto trong controller.
• Content negotiation: Spring chọn converter dựa trên Accept header. Không tìm được converter → 406 Not Acceptable.
• Dùng ResponseEntity đúng chỗ: chỉ khi cần custom status, custom header, hoặc body điều kiện. GET đơn giản trả 200 thì return DTO trực tiếp.

Tự kiểm tra

@PostMapping("/products")
public ProductDto create(@Valid @RequestBody ProductRequest req) {
  return productService.create(req);
}

@DeleteMapping("/products/{id}")
public ProductDto delete(@PathVariable Long id) {
  productService.delete(id);
  return null;
}

@PostMapping("/products")
public ResponseEntity<ProductDto> create(@Valid @RequestBody ProductRequest req) {
  ProductDto created = productService.create(req);
  URI location = ServletUriComponentsBuilder.fromCurrentRequest()
      .path("/{id}").buildAndExpand(created.id()).toUri();
  return ResponseEntity.created(location).body(created);
}

@DeleteMapping("/products/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void delete(@PathVariable Long id) {
  productService.delete(id);
}

@GetMapping("/orders/{id}")
public ResponseEntity<OrderDto> get(
  @PathVariable Long id,
  @RequestHeader(value = "If-None-Match", required = false) String ifNoneMatch
) {
  return orderService.findOptional(id)
      .map(order -> {
          String etag = "\"" + order.version() + "\"";
          // 304: version chua thay doi, khong can gui lai body
          if (etag.equals(ifNoneMatch)) {
              return ResponseEntity.<OrderDto>status(HttpStatus.NOT_MODIFIED).build();
          }
          // 200: co body + ETag de client cache
          return ResponseEntity.ok()
              .eTag(etag)
              .body(order);
      })
      // 404: khong tim thay
      .orElseGet(() -> ResponseEntity.notFound().build());
}

@DeleteMapping("/orders/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void delete(@PathVariable Long id) {
  orderService.delete(id);
}
// Ngan hon: khong can ResponseEntity<Void>, khong can .build()

@PostMapping("/orders/{id}/archive")
@ResponseStatus(HttpStatus.ACCEPTED)
public void archiveAsync(@PathVariable Long id) {
  archiveService.scheduleArchive(id);
  // 202 Accepted -- viec nay chay async, khong tra ket qua ngay
}

// HTTP/1.1 404 Not Found
// Content-Type: application/problem+json
{
"type": "https://api.example.com/errors/not-found",
"title": "Order not found",
"status": 404,
"detail": "Order with id 42 does not exist",
"instance": "/api/orders/42"
}

Bài tiếp theo: Streaming, ResponseBodyAdvice và HATEOAS