Cách sửa lỗi 'Request method POST not supported' trong Spring Boot

Cách khắc phục trong 30 giây

Ngoại lệ HttpRequestMethodNotSupportedException xảy ra khi loại yêu cầu của bạn (như POST) không khớp với loại được định nghĩa trong Spring Controller (như GET). Dưới đây là danh sách kiểm tra để bạn khắc phục ngay lập tức:

Kiểm tra annotation: Sử dụng @PostMapping nếu bạn đang gửi dữ liệu.
Kiểm tra URL: Có thể bạn đang gọi nhầm vào một endpoint chỉ hỗ trợ GET.
Xác minh phía client: Đảm bảo Postman, cURL hoặc frontend của bạn không mặc định gửi yêu cầu GET.

Tại sao lỗi này lại xảy ra?

Spring MVC dựa vào HandlerMapping để điều hướng lưu lượng truy cập đến @RestController của bạn. Nó hoạt động như một bộ điều phối giao thông kiểm tra hai thứ: URL path và HTTP verb (GET, POST, PUT, v.v.).

Khi ngoại lệ này xuất hiện, Spring thực tế đã tìm thấy một URL phù hợp. Vấn đề là phương thức cụ thể mà bạn đang gọi không được thiết lập để xử lý HTTP verb mà bạn đã gửi. Ví dụ: nếu bạn gọi một endpoint @GetMapping bằng yêu cầu POST, Spring sẽ chặn nó. Sau đó, nó ném ra ngoại lệ này và trả về mã trạng thái 405 Method Not Allowed cho client.

Những nguyên nhân thường gặp

1. Sai lệch Annotation

Đây là nguyên nhân trong khoảng 90% trường hợp. Bạn có thể định lưu dữ liệu nhưng vô tình sử dụng sai annotation mapping.

Mã nguồn bị lỗi:

@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    // Endpoint này chỉ lắng nghe yêu cầu GET
    @GetMapping("/save")
    public ResponseEntity<String> saveUser(@RequestBody User user) {
        return ResponseEntity.ok("User saved");
    }
}

Nếu bạn gửi một yêu cầu POST đến /api/v1/users/save, nó sẽ thất bại. Tại sao? Bởi vì @GetMapping chỉ cho phép đọc dữ liệu, không cho phép gửi dữ liệu.

Mã nguồn đã sửa:

@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    @PostMapping("/save") // Bây giờ nó đã chấp nhận các yêu cầu POST
    public ResponseEntity<String> saveUser(@RequestBody User user) {
        return ResponseEntity.status(201).body("User created with ID: 101");
    }
}

2. Lỗi đánh máy và Path Variables

Những lỗi đánh máy nhỏ trong URL có thể dẫn Spring đến sai phương thức. Hãy xem xét hai endpoint sau:

GET /api/products/{id} (Lấy thông tin một sản phẩm)
POST /api/products (Tạo sản phẩm mới)

Nếu bạn vô tình gọi POST /api/products/123, Spring sẽ khớp đường dẫn đó với phương thức GET. Sau đó, nó nhận thấy bạn đang cố gắng sử dụng POST trên một đường dẫn cụ thể theo ID và ném ra ngoại lệ vì route cụ thể đó không hỗ trợ POST.

3. Cơ chế bảo vệ CSRF trong Spring Security

Spring Security bật tính năng bảo vệ Cross-Site Request Forgery (CSRF) theo mặc định. Thông thường, điều này sẽ kích hoạt lỗi 403 Forbidden. Tuy nhiên, các bộ lọc bảo mật tùy chỉnh hoặc chuyển hướng nội bộ đôi khi có thể che lấp vấn đề thực sự, dẫn đến lỗi 405 gây nhầm lẫn.

Nếu bạn đang xây dựng một stateless REST API sử dụng JWT, bạn có thể tắt CSRF trong cấu hình của mình một cách an toàn:

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
        .csrf(csrf -> csrf.disable()) 
        .authorizeHttpRequests(auth -> auth.anyRequest().permitAll());
    return http.build();
}

Cách xác minh việc khắc phục

Đừng phụ thuộc vào trình duyệt để kiểm tra điều này, vì trình duyệt thường lưu cache kết quả hoặc mặc định là GET. Hãy sử dụng curl để xem chính xác những gì máy chủ trả về.

Chạy lệnh này trong terminal của bạn:

curl -i -X POST http://localhost:8080/api/v1/users/save \
     -H "Content-Type: application/json" \
     -d '{"name": "Alice", "email": "alice@example.com"}'

Việc khắc phục thành công sẽ trả về mã 200 OK hoặc 201 Created. Nếu vẫn thất bại, cờ -i sẽ hiển thị cho bạn chính xác các headers và mã trạng thái mà máy chủ trả về.

Đọc log như một chuyên gia

Kiểm tra đầu ra console của bạn. Spring cung cấp một gợi ý rõ ràng khi xử lý ngoại lệ này:

WARN 45210 --- [nio-8080-exec-1] .w.s.m.s.DefaultHandlerExceptionResolver : Resolved [org.springframework.web.HttpRequestMethodNotSupportedException: Request method 'POST' not supported. Available methods: [GET]]

Bản ghi log này là một "mỏ vàng". Nó liệt kê rõ ràng các Available methods. Nếu nó ghi [GET], bạn biết chắc chắn rằng controller của mình đang thiếu annotation @PostMapping.

Các bước tiếp theo

Xem lại tài liệu Spring @RequestMapping.
Đảm bảo các lệnh gọi fetch/axios ở frontend chỉ định đúng thuộc tính method.
Chuẩn hóa các đường dẫn API của bạn để tránh nhầm lẫn giữa tập hợp tài nguyên và các mục riêng lẻ.