Trong Spring MVC, bạn viết một method trong @Controller, return "tasks";, và nhận về 500 với thông báo Error resolving template [tasks]. Đổi class sang @RestController, giữ nguyên method, và body response chỉ còn đúng chuỗi tasks. Không có gì bí ẩn: hai annotation chọn hai return value handler khác nhau, và bài này dựng một app task list chạy được để chỉ ra chỗ hai đường tách nhau.
Toàn bộ code dưới đây chạy trên Spring Boot 4.1.2, Java 25 LTS, Maven 3.10. Bạn cần JDK 25 và không cần cài Tomcat, không cần web.xml.
Mục lục
Cập nhật 2026
- Starter đổi tên. Boot 4.1 deprecate
spring-boot-starter-webvà khuyến nghịspring-boot-starter-webmvc. Starter mới kéospring-boot-webmvc, Tomcat 11 (Servlet 6.1) và Jackson. Dùng tên cũ vẫn chạy, nhưng code mới nên theo tên mới. - Test slice tách ra starter riêng.
@WebMvcTestnằm trongspring-boot-starter-webmvc-test(scope test), packageorg.springframework.boot.webmvc.test.autoconfigure. Chỉ thêmspring-boot-starter-testlà không đủ để có annotation này. - Jakarta EE 11 là baseline. Validation dùng
jakarta.validation.*; mọijavax.*đã bị loại bỏ khỏi Framework 7. - JSON mặc định là Jackson 3. Boot 4.1.2 quản lý BOM Jackson 3.1.7, package
tools.jackson.*. Code chỉ dùng DTO và annotation nên không phải sửa gì.
Spring MVC: hai đường đi của một giá trị trả về
Một request vào DispatcherServlet, được HandlerMapping khớp tới method controller, rồi HandlerAdapter gọi method đó. Phần quyết định nằm sau khi method trả về: một HandlerMethodReturnValueHandler được chọn, và nó quyết định kết quả là body hay là tên view. Cơ chế đầy đủ của chuỗi này ở bài DispatcherServlet và những người bạn; ở đây chỉ cần hai nhánh.
| Nhánh | Ai xử lý kết quả | Ra gì trên dây |
|---|---|---|
Có @ResponseBody (hoặc @RestController) |
RequestResponseBodyMethodProcessor + HttpMessageConverter |
Body theo Accept/Content-Type, thường là JSON |
Không có @ResponseBody (@Controller) |
ViewNameMethodReturnValueHandler + ViewResolver |
HTML do template render, hoặc 500 nếu không tìm thấy template |
Vì vậy cùng một String có hai nghĩa. Trong @Controller nó là tên view logic; trong @RestController nó là dữ liệu để converter ghi ra. Đây là toàn bộ lý do hai annotation tồn tại.
Dựng project từ Spring Initializr
Trên start.spring.io chọn Maven, Java 25, Boot 4.1.2, group com.example, artifact taskboard, dependencies Spring Web, Validation, Thymeleaf. Initializr sinh wrapper mvnw, class chính và starter test. Phần pom.xml quan trọng gồm:
<!-- File: pom.xml -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.1.2</version>
<relativePath/>
</parent>
<properties>
<java.version>25</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
spring-boot-starter-validation kéo Hibernate Validator 9.1.5 và Jakarta Validation 3.1.1; thân starter webmvc không kèm validator. Bỏ dependency này thì jakarta.validation.Valid không còn trên classpath và code không compile; nếu chỉ thiếu implementation, annotation vẫn qua compile nhưng không có ai kiểm tra, và lỗi chỉ lộ ra lúc chạy.
Lớp khởi động và vị trí package
// File: src/main/java/com/example/taskboard/TaskboardApplication.java
package com.example.taskboard;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class TaskboardApplication {
public static void main(String[] args) {
SpringApplication.run(TaskboardApplication.class, args);
}
}
@SpringBootApplication gồm @EnableAutoConfiguration và @ComponentScan. Component scan lấy package của class chính làm gốc, nên mọi controller, service, advice phải nằm trong com.example.taskboard hoặc package con. Đặt class chính vào com.example.taskboard.web là cách nhanh nhất để có 404 mà không có log nào đáng ngờ.
DTO, service và endpoint JSON
Hai record, một cho input có validation, một cho output. Tách chúng ngay từ đầu để sau này thêm JPA không phải sửa API.
// File: src/main/java/com/example/taskboard/task/TaskRequest.java
package com.example.taskboard.task;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
public record TaskRequest(
@NotBlank(message = "Tiêu đề không được để trống")
@Size(max = 120, message = "Tiêu đề tối đa 120 ký tự")
String title,
boolean done) {
}
// File: src/main/java/com/example/taskboard/task/Task.java
package com.example.taskboard.task;
public record Task(long id, String title, boolean done) {
}
Jackson 3 lấy tên field từ component của record, không cần getter, nên JSON có đúng id, title, done. Record cũng bất biến, hợp làm DTO trả ra hơn là một entity có setter.
// File: src/main/java/com/example/taskboard/task/TaskService.java
package com.example.taskboard.task;
import java.util.Comparator;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicLong;
import org.springframework.stereotype.Service;
@Service
public class TaskService {
private final Map<Long, Task> tasks = new ConcurrentHashMap<>();
private final AtomicLong ids = new AtomicLong();
public List<Task> findAll() {
return tasks.values().stream()
.sorted(Comparator.comparingLong(Task::id))
.toList();
}
public Optional<Task> find(long id) {
return Optional.ofNullable(tasks.get(id));
}
public Task create(TaskRequest request) {
long id = ids.incrementAndGet();
Task task = new Task(id, request.title(), request.done());
tasks.put(id, task);
return task;
}
}
// File: src/main/java/com/example/taskboard/task/TaskApiController.java
package com.example.taskboard.task;
import java.net.URI;
import java.util.List;
import jakarta.validation.Valid;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/api/tasks")
public class TaskApiController {
private final TaskService service;
public TaskApiController(TaskService service) {
this.service = service;
}
@GetMapping
public List<Task> list() {
return service.findAll();
}
@GetMapping("/{id}")
public Task byId(@PathVariable long id) {
return service.find(id).orElseThrow(() -> new TaskNotFoundException(id));
}
@PostMapping
public ResponseEntity<Task> create(@Valid @RequestBody TaskRequest request) {
Task created = service.create(request);
return ResponseEntity.created(URI.create("/api/tasks/" + created.id())).body(created);
}
}
Ba điểm đáng chú ý. @RequestBody bảo converter đọc JSON từ body; thiếu nó, Spring coi body là nguồn bind cho model attribute và record không có setter sẽ nhận title = null. @Valid là công tắc bật validation trong argument resolver, bản thân các annotation constraint không tự chạy. ResponseEntity.created(...) cho 201 kèm header Location, thay vì 200 ngầm hiểu.
400 và 404 theo RFC 9457 với ProblemDetail
Ném một exception riêng cho trường hợp không tìm thấy, rồi map nó ở một chỗ duy nhất.
// File: src/main/java/com/example/taskboard/task/TaskNotFoundException.java
package com.example.taskboard.task;
public class TaskNotFoundException extends RuntimeException {
public TaskNotFoundException(long id) {
super("Task " + id + " khong ton tai");
}
}
// File: src/main/java/com/example/taskboard/web/ApiExceptionHandler.java
package com.example.taskboard.web;
import java.util.LinkedHashMap;
import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import com.example.taskboard.task.TaskNotFoundException;
@RestControllerAdvice
public class ApiExceptionHandler {
@ExceptionHandler(TaskNotFoundException.class)
ProblemDetail notFound(TaskNotFoundException ex) {
ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
problem.setTitle("Task not found");
return problem;
}
@ExceptionHandler(MethodArgumentNotValidException.class)
ProblemDetail invalid(MethodArgumentNotValidException ex) {
ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, "Du lieu khong hop le");
problem.setTitle("Validation failed");
Map<String, String> errors = new LinkedHashMap<>();
ex.getBindingResult().getFieldErrors()
.forEach(error -> errors.put(error.getField(), error.getDefaultMessage()));
problem.setProperty("errors", errors);
return problem;
}
}
@RestControllerAdvice là @ControllerAdvice cộng @ResponseBody, đúng cho API JSON. Trả về ProblemDetail thì status lấy từ chính object đó, body có type, title, status, detail và Content-Type: application/problem+json. setProperty thêm field không chuẩn, ở đây là map lỗi theo tên field.
Boot cũng có sẵn handler cho exception của chính framework, bật bằng spring.mvc.problemdetails.enabled=true, mặc định tắt. 400 và 404 ở đây do advice của bạn xử lý nên không cần property đó; bật nó nếu muốn 405 hay 415 cũng ra cùng format.
Trang Thymeleaf với @Controller
// File: src/main/java/com/example/taskboard/web/TaskPageController.java
package com.example.taskboard.web;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import com.example.taskboard.task.TaskService;
@Controller
public class TaskPageController {
private final TaskService service;
public TaskPageController(TaskService service) {
this.service = service;
}
@GetMapping("/tasks")
public String tasks(Model model) {
model.addAttribute("tasks", service.findAll());
return "tasks";
}
}
<!-- File: src/main/resources/templates/tasks.html -->
<!DOCTYPE html>
<html lang="vi" xmlns:th="http://www.thymeleaf.org">
<head>
<meta charset="UTF-8">
<title>Task list</title>
</head>
<body>
<h1>Task list</h1>
<ul>
<li th:each="task : ${tasks}" th:text="${task.title}">Ten task</li>
</ul>
</body>
</html>
Starter Thymeleaf đăng ký ThymeleafViewResolver với prefix classpath:/templates/ và suffix .html. Tên view tasks thành src/main/resources/templates/tasks.html. Method trả String và không có @ResponseBody, nên ViewNameMethodReturnValueHandler nhận nó, rồi resolver render; Model được đổ vào template qua các biến tasks.
Muốn text thuần từ một @Controller mà không render template, thêm @ResponseBody lên method. Đừng đổi sang @RestController cho cả class chỉ vì một method, vì các method còn lại sẽ mất khả năng trả tên view.
Chạy và kiểm tra bằng curl
# Windows: .\mvnw.cmd spring-boot:run
./mvnw spring-boot:run
curl -i http://localhost:8080/api/tasks
curl -i -X POST http://localhost:8080/api/tasks \
-H "Content-Type: application/json" \
-d '{"title":"Viet bai Spring MVC","done":false}'
curl -i http://localhost:8080/api/tasks/999
curl -i -X POST http://localhost:8080/api/tasks \
-H "Content-Type: application/json" \
-d '{"title":"","done":false}'
Kết quả mong đợi: lần lượt 200 với mảng rỗng, 201 kèm Location: /api/tasks/1, 404 với application/problem+json, và 400 với errors.title chứa message tiếng Việt. Dùng curl -i để thấy status và Content-Type; nếu chỉ nhìn body, bạn dễ nhầm một 200 rỗng với thành công. Quên header Content-Type: application/json ở request POST thì Spring trả 415 trước khi controller chạy, vì không converter nào nhận ra body.
Mở http://localhost:8080/tasks để xem nhánh view. Cùng app, hai controller, hai kiểu response, không cấu hình gì thêm.
Test slice với @WebMvcTest
// File: src/test/java/com/example/taskboard/task/TaskApiControllerTest.java
package com.example.taskboard.task;
import static org.mockito.BDDMockito.given;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import java.util.Optional;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
import org.springframework.test.context.bean.override.mockito.MockitoBean;
import org.springframework.test.web.servlet.MockMvc;
@WebMvcTest(TaskApiController.class)
class TaskApiControllerTest {
@Autowired
MockMvc mvc;
@MockitoBean
TaskService service;
@Test
void returnsTaskAsJson() throws Exception {
given(service.find(1L)).willReturn(Optional.of(new Task(1L, "Viet bai", false)));
mvc.perform(get("/api/tasks/1"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.title").value("Viet bai"));
}
}
@WebMvcTest chỉ nạp tầng web: controller, advice, converter, filter. TaskService không nằm trong slice, nên @MockitoBean thay nó bằng mock; @MockBean đã bị xóa khỏi Boot 4. Nếu dùng @SpringBootTest thay vì slice, bạn phải thêm @AutoConfigureMockMvc mới có bean MockMvc.
Từ Framework 6.2 có thêm MockMvcTester trong package org.springframework.test.web.servlet.assertj, bọc MockMvc và cho assertion kiểu AssertJ. Nó có mặt trong 7.0.10, nhưng MockMvc cổ điển vẫn là API ổn định nhất để bắt đầu.
Sáu lỗi hay gặp
- Class chính ở sai package. Component scan chỉ đi xuống từ package của class chính, nên controller ở package anh em không được đăng ký. Endpoint trả 404, log không nhắc gì. Giữ class chính ở gốc, hoặc khai báo
scanBasePackagescó chủ đích. - Thiếu
@RequestBody. Body JSON không được converter đọc; Spring bind theo request param và record nhậnnull. Nếu không có validation, một task rỗng vẫn được tạo và bạn mất thời gian tìm lỗi ở frontend. - Trả entity thay vì DTO. Với JPA, entity managed và quan hệ lazy làm Jackson 3 ném lỗi hoặc serialize cả bảng. Record DTO là biên rõ ràng: đổi schema không đổi hợp đồng API.
- Thiếu
@Valid.@NotBlank,@Sizechỉ là metadata cho validator; argument resolver chỉ chạy validation khi thấy@Valid. Thiếu nó, mọi body đều lọt. ProblemDetailkhông ra JSON. MộtErrorControllertự viết, mộtHandlerExceptionResolverhoặc filter ghi body riêng và chạy trước advice sẽ nuốt format chuẩn. Kiểm traContent-Typecó đúngapplication/problem+jsonkhông.- Tên template lệch.
return "tasks"tìm đúngtemplates/tasks.html; đặt file trongstatic/thì nó được phục vụ như file tĩnh chứ không render. Đổispring.thymeleaf.prefixcũng đổi đường dẫn, nên kiểm tra property trước khi sửa code.
Chọn @RestController hay @Controller
| Bạn cần | Dùng | Lý do |
|---|---|---|
| API JSON cho web/mobile | @RestController |
Kết quả đi qua converter, không qua ViewResolver |
| Trang HTML render template | @Controller |
String là tên view, Model là dữ liệu cho template |
| Cả hai trong một app | Tách hai class | Mỗi class một kiểu return value, không trộn @ResponseBody ở cấp class |
Nhìn về 2027
Boot 4.2.0-RC2 và Framework 7.1.0-RC2 đang ở RC, chưa phát hành. Hai thứ đáng thử khi chúng ra: API versioning ngay trong mapping (Framework 7.0 có attribute version trên @RequestMapping), và spring.threads.virtual.enabled=true cho virtual threads trên Java 25. Cả hai đều là lựa chọn, không phải mặc định, nên app đầu tiên không cần chúng.
Checklist
- Class chính ở package gốc của app; controller, service, advice nằm dưới nó.
@RestControllercho JSON,@Controllercho view; không trộn hai kiểu trong một class.- Input có
@RequestBodyvà@Valid; output là record DTO, không phải entity. - Lỗi trả
ProblemDetailtừ một@RestControllerAdvice, và kiểm traContent-Typebằng curl. - Template đặt đúng
src/main/resources/templates; test slice dùngspring-boot-starter-webmvc-test.
Đọc tiếp các thành phần thiết yếu của một ứng dụng web Spring MVC để hiểu converter và content negotiation, Spring Boot starters để biết starter nào kéo module nào, và Spring Boot Roadmap để đặt bài này vào đúng chặng.



