User Page

# 1. Restful API trong Spring Boot ## 1.1. Giới thiệu `Restful API` là một kiến trúc phần mềm dựa trên giao thức `HTTP` mà các `API` đều được xây dựng dựa trên các phương thức `HTTP` như `GET`, `POST`, `PUT`, `DELETE`. `Restful API` không lưu trạng thái của `client` trên `server`, mà nó sẽ lưu trạng thái của `client` trên `client` và `server` sẽ không lưu trạng thái của `client`. ## 1.2. Tạo Restful API trong Spring Boot ### 1.2.1. Tạo Restful API Để tạo `Restful API` trong `Spring Boot`, chúng ta sẽ tạo một `Controller` và sử dụng các annotation của `Spring` như `@RestController`, `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`. Khác với `Spring MVC`, `Spring Boot` không sử dụng `@Controller` mà sử dụng `@RestController`. Khác với `Spring MVC`, `Spring Boot` không sử dụng `@RequestMapping(value="/", RequestMethod.GET, ....)` mà sử dụng `@GetMapping(path="/")`, `@PostMapping(path="/")`, `@PutMapping(path="/")`, `@DeleteMapping(path="/")` Trong các Annotation trên có các tham số như: - `path`: Đường dẫn của `API`. Dạng String[] VD: + path = "/hello" thì `API` sẽ là `http://localhost:8080/hello`. + path = {"/hello", "/hi"} thì `API` sẽ là `http://localhost:8080/hello` và `http://localhost:8080/hi` sẽ cùng gọi vào phương thức đó. - `params`: Điều kiện để `API` được gọi. Dạng String[] VD: + params = "id=1" thì `API` chỉ được gọi khi có tham số `id` và giá trị là `1`. `http://localhost:8080/hello?id=1`. + params = {"id=1", "name=Didan"} thì `API` chỉ được gọi khi có tham số `id` và giá trị là `1` và `name` và giá trị là `Didan`. `http://localhost:8080/hello?id=1&name=Didan`. - `consumes`: Định dạng dữ liệu `client` gửi lên. Dạng String[] VD: + consumes = {MediaType.APPLICATION_JSON_VALUE} thì chỉ chấp nhận dữ liệu dạng `JSON`. + consumes = {MediaType.APPLICATION_XML_VALUE} thì chỉ chấp nhận dữ liệu dạng `XML`. + consumes = {MediaType.APPLICATION_FORM_URLENCODED_VALUE} thì chỉ chấp nhận dữ liệu dạng `FormUrlEncoded`. + consumes = {MediaType.MULTIPART_FORM_DATA_VALUE} thì chỉ chấp nhận dữ liệu dạng `Multipart/Form`. - `produces`: Định dạng dữ liệu `server` trả về. Dạng String[] VD: + produces = {MediaType.APPLICATION_JSON_VALUE} thì chỉ trả về dữ liệu dạng `JSON`. + produces = {MediaType.APPLICATION_XML_VALUE} thì chỉ trả về dữ liệu dạng `XML`. + produces = {MediaType.TEXT_PLAIN_VALUE} thì chỉ trả về dữ liệu dạng `Text`. + produces = {MediaType.APPLICATION_PDF_VALUE} thì chỉ trả về dữ liệu dạng `PDF`. - `headers`: Gửi `Header` cụ thể để gọi `API`. thuộc dang String[] + headers = "key=value" thì chỉ gọi `API` khi có `Header` có key là `key` và value là `value`. + headers = {"key1=value1", "key2=value2"} thì chỉ gọi `API` khi có `Header` có key1 là `value1` và key2 là `value2`. Ví dụ: ```java Thay vì trả về `View` như `Spring MVC`, `@RestController` sẽ trả về dữ liệu dưới dạng `JSON` hoặc `XML`. ```java package com.didan.spring_boot_web.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @RestController // Đánh dấu đây là một RestController public class HelloController { @GetMapping(path = "/hello") // Khi có request GET đến /hello thì phương thức này sẽ được gọi public String hello() { return "Hello World!"; } } ``` Khi chúng ta truy cập vào `http://localhost:8080/hello` thì sẽ nhận được dữ liệu `Hello World!`. Nhưng dữ liệu ở đây chỉ là dạng `String`, `Text` chứ không phải là `JSON` hoặc `XML`. ### 1.2.2. Trả về dữ liệu dưới dạng JSON Để trả về dữ liệu dưới dạng `JSON`, chúng ta trả về Bean hoặc `List` của Bean. `Spring Boot` sẽ tự động chuyển đổi Bean hoặc `List` của Bean sang dạng `JSON` nhờ `@ResponseBody` và `JacksonHttpMessageConverter` (đã được tích hợp sẵn trong `Spring Boot`). Lưu ý Bean cần có `getter` và `setter` hoặc `constructor` có tham số để map dữ liệu truyền vào và chuyển đổi dữ liệu sang dạng `JSON`. Ví dụ: >HelloBean.java ```java package com.didan.spring_boot_web.bean; public class HelloBean { private String message; public HelloBean(String message) { this.message = message; } public String getMessage() { return message; } public void setMessage(String message) { this.message = message; } public String toString() { return String.format("HelloBean [message=%s]", message); } } ``` > HelloController.java ```java package com.didan.spring_boot_web.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @RestController public class HelloController { @GetMapping(path = "/hello") public HelloBean hello() { return new HelloBean("Hello World!"); } } ``` Khi chúng ta truy cập vào `http://localhost:8080/hello` thì sẽ nhận được dữ liệu dưới dạng `JSON`: ```json { "message": "Hello World!" } ``` ### 1.2.3. Thiết lập params, query cho Restful API Để thiết lập `params`, `query` cho `Restful API`, chúng ta sử dụng `@RequestParam` cho `query` và `@PathVariable` cho `params`. Ví dụ: ```java package com.didan.spring_boot_web.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; @RestController public class HelloController { @GetMapping(path = "/hello/{id}") public HelloBean hello(@RequestParam("name") String name, @PathVariable("id") String id) { return new HelloBean("Hello " + name + " with id " + id); } // VD: http://localhost:8080/hello/1?name=Didan => {"message":"Hello Didan with id 1"} } ``` ### 1.2.4. Sử dụng `@RequestBody`, `@ModelAttribute`, `@RequestHeader` trong Restful API để nhận dữ liệu từ `client` - `@RequestBody`: Dùng để nhận dữ liệu từ `client` dưới dạng `JSON` hoặc `XML`. - `@ModelAttribute`: Dùng để nhận dữ liệu từ `client` dưới dạng `FormUrlEncoded`, `Multipart/Form`. Ví dụ: ```java package com.didan.spring_boot_web.controller; import com.didan.spring_boot_web.bean.HelloBean; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RestController; import org.springframework.web.bind.annotation.ModelAttribute; import org.springframework.web.bind.annotation.RequestBody; @RestController public class HelloController { @PostMapping(path = "/hello") public HelloBean hello(@RequestBody HelloBean helloBean) { return helloBean; } // VD: http://localhost:8080/hello với body là {"message":"Hello Didan"} => {"message":"Hello Didan"} @PostMapping(path = "/hello") public HelloBean hello(@ModelAttribute HelloBean helloBean) { return helloBean; } // VD: http://localhost:8080/hello với body là message=Hello%20Didan => {"message":"Hello Didan"} @GetMapping(path = "/header") public HelloBean header(@RequestHeader MultiValueMap headers) { // Lấy ra tất cả các Header headers.forEach((key, value) -> { System.out.println(key + ": " +value); }); return new HelloBean("Hello " + name); } @GetMapping(path = "/header-2") public HelloBean header(@RequestHeader("name") String name) { // Lấy ra giá trị của Header có key là name return new HelloBean("Hello " + name); } } ``` ### 1.2.5. Trả về `ResponseEntity` trong Restful API `ResponseEntity` là một class trong `Spring` dùng để trả về `HTTP Status`, `Header`, `Body`. Chúng ta có thể trả về `ResponseEntity` trong `Restful API` để trả về `HTTP Status` khác nhau, `Header` khác nhau. Có thể trả về `ResponseEntity` với dữ liệu dạng `JSON`, `XML`, `String`, `Object`. Có 3 cách để trả về `ResponseEntity` theo thứ tự tham số truyền vào: - Trả về `ResponseEntity` với chỉ `Body` - Trả về `ResponseEntity` với `Body` và `HTTP Status` - Trả về `ResponseEntity` với `Body`, `Header` và `HTTP Status` Để có thể trả về `ResponseEntity` chúng ta phải đặt dữ liệu trả về là `ResponseEntity` vào phương thức. Ví dụ: > Trả về `ResponseEntity` với`Body`,`Header` và `HTTP Status` do chúng ta thiết lập. ```java package com.didan.spring_boot_web.controller; import com.didan.spring_boot_web.bean.HelloBean; import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; import org.springframework.util.LinkedMultiValueMap; import org.springframework.util.MultiValueMap; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @RestController public class HelloController { @GetMapping(path = "/hello") public ResponseEntity hello() { // Kiểu trả về phải là ResponseEntity HelloBean helloBean = new HelloBean("Hello World!"); URI location = ServletUriComponentsBuilder.fromCurrentRequest() // Lây ra URI từ request hiện tại .path("/{id}") // Thêm một path vào URI với id là tham số truyền vào .buildAndExpand(helloBean.getMessage()) // Thêm tham số vào path vừa tạo .toUri(); // Chuyển URI thành URI object MultiValueMap headers = new LinkedMultiValueMap<>(); // Tạo một MultiValueMap để lưu trữ Header headers.add("location", location.toString()); // Thêm một Header vào MultiValueMap với key là location, value là URI. Để cho client biết nơi lấy dữ liệu return new ResponseEntity<>(helloBean, headers, HttpStatus.OK); // Trả về ResponseEntity với Body là helloBean, Header là headers, HTTP Status là OK, lưu ý thứ tự truyền vào và không có kiểu trả về bên trong ResponseEntity<> } } ``` ## 1.3. Bắt Exception trong Restful API khi xảy ra lỗi truy vấn dữ liệu Khi xảy ra lỗi trong quá trình truy vấn dữ liệu, chúng ta cần bắt lỗi đó và trả về thông báo lỗi cho `client`. ### 1.3.1. Tạo class kế thừa `RuntimeException` để tạo `Custom Exception` Để bắt lỗi, ta sử dụng `RuntimeException` để bắt lỗi và trả về thông báo lỗi cho `client`. `RuntimeException` khác với `Exception` ở chỗ là `RuntimeException` không cần phải khai báo trong phương thức, nó sẽ tự động bắt lỗi khi xảy ra. Ngoài ra để tùy chỉnh thông báo lỗi + mã lỗi, chúng ta sử dụng `@ResponseStatus` để thiết lập `HTTP Status` cho `Response`. Và tạo 1 class kế thừa `RuntimeException` để tạo ra `Custom Exception`. Ví dụ: Nếu `id` truyền vào không tồn tại trong `database` thì sẽ trả về `HTTP Status` là `NOT_FOUND` và thông báo lỗi là `ID not found`. > NotFoundException.java ```java package com.didan.spring_boot_web.exception; import org.springframework.http.HttpStatus; import org.springframework.web.bind.annotation.ResponseStatus; @ResponseStatus(code = HttpStatus.NOT_FOUND) // Thiết lập HTTP Status là NOT_FOUND public class NotFoundException extends RuntimeException { // Kế thừa RuntimeException public NotFoundException(String message) { // Constructor với tham số là message super(message); // Gọi constructor của class cha với tham số là message } } ``` > HelloController.java ```java ... @RestController public class HelloController { @GetMapping(path = "/hello/{id}") public ResponseEntity hello(@PathVariable("id") String id) { if (!id.equals("1")) { // Nếu id khác 1 thì ném ra NotFoundException throw new NotFoundException("ID not found"); // Ném ra NotFoundException với message là ID not found } return new ResponseEntity<>(helloBean, HttpStatus.OK); } } ``` Khi chúng ta truy cập vào `http://localhost:8080/hello/2` thì sẽ nhận được thông báo lỗi `ID not found` và `HTTP Status` là `NOT_FOUND`. Nếu sử dụng `Postman` thì thông báo lỗi sẽ tự chuyển về dạng `JSON`. Nếu muốn Web trả về thông báo lỗi dưới dạng `JSON` thì xem bước tiếp theo. ### 1.3.2. Sử dụng `@ExceptionHandler` để tùy chỉnh trường thông tin lỗi trả về cho `client` Để tùy chỉnh thông báo lỗi trả về cho `client` dưới dạng `JSON`, chúng ta sử dụng `@ExceptionHandler` để bắt lỗi và trả về thông báo lỗi dưới dạng `JSON`. Mặc định `Spring Boot` sẽ trả về thông báo lỗi dưới dạng `HTML` nếu không tùy chỉnh, và dùng Postman để test thì thông báo lỗi sẽ không đẹp. VD: ```json { "timestamp": "2021-07-07T08:00:00.000+00:00", "status": 404, "error": "Not Found", "message": "ID not found", "path": "/hello/2" } ``` Trước tiên tạo một class để tùy chỉnh các trường thông tin lỗi trả về cho `client`. > CustomErrorResponse.java ```java package com.didan.spring_boot_web.exception; import java.util.LocalDateTime; public class CustomErrorResponse { private LocalDateTime timestamp; private String message; private String details; public CustomErrorResponse(LocalDateTime timestamp, String message, String details) { this.timestamp = timestamp; this.message = message; this.details = details; } // Getter và Setter .... } ``` Sau đó tạo một class để xử lý lỗi và trả về thông báo lỗi dưới dạng `JSON`. Sử dụng kế thừa lớp `ResponseEntityExceptionHandler` để xử lý lỗi. > CustomResponseEntityExceptionHandler.java ```java package com.didan.spring_boot_web.exception; import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.ControllerAdvice; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.context.request.WebRequest; import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler; import java.time.LocalDateTime; @ControllerAdvice // Đánh dấu đây là một class xử lý lỗi cho tất cả các Controller public class CustomResponseEntityExceptionHandler extends ResponseEntityExceptionHandler { // Kế thừa lớp ResponseEntityExceptionHandler để xử lý lỗi // Tạo một method để xử lý lỗi chung cho tât cả các Controller @ExceptionHandler(Exception.class) // Bắt lỗi cho bất kỳ method ném ra lỗi public final ResponseEntity handleAllExceptions(Exception ex, WebRequest request) { CustomErrorResponse customErrorResponse = new CustomErrorResponse(LocalDateTime.now(), ex.getMessage(), request.getDescription(false)); // Tạo một CustomErrorResponse với thông tin lỗi là message của Exception và details là URL của request return new ResponseEntity<>(customErrorResponse, HttpStatus.INTERNAL_SERVER_ERROR); // Trả về ResponseEntity với Body là customErrorResponse, HTTP Status là INTERNAL_SERVER_ERROR } // Tạo một method để xử lý lỗi cho lỗi cụ thể NotFoundException @ExceptionHandler(NotFoundException.class) // Bắt lỗi cho bất kỳ method ném ra NotFoundException public final ResponseEntity handleNotFoundException(NotFoundException ex, WebRequest request) { // WebRequest là một interface để lấy thông tin của request như URL, Header, Body, ... CustomErrorResponse customErrorResponse = new CustomErrorResponse(LocalDateTime.now(), ex.getMessage(), request.getDescription(false)); // Tạo một CustomErrorResponse với thông tin lỗi là message của Exception và details là URL của request return new ResponseEntity<>(customErrorResponse, HttpStatus.NOT_FOUND); // Trả về ResponseEntity với Body là customErrorResponse, HTTP Status là NOT_FOUND } } ``` Sau khi tạo xong `CustomResponseEntityExceptionHandler`, khi chúng ta truy cập vào `http://localhost:8080/hello/2` thì sẽ nhận được thông báo lỗi dưới dạng `JSON`: ```json { "timestamp": "2021-07-07T08:00:00.000+00:00", "message": "ID not found", "details": "/hello/2" } ``` ## 1.4. Sử dụng `Validation` trong Spring Boot RESTful API Để sử dụng `Validation` trong Spring Boot RESTful API, chúng ta cần thực hiện các bước sau: ### 1.4.1. Thêm `dependency` vào `pom.xml` ```xml org.springframework.boot spring-boot-starter-validation ``` ### 1.4.2. Tạo `Command Bean` chứa dữ liệu cần kiểm tra Tạo ra một class chứa dữ liệu cần kiểm tra, class này sẽ được gọi là `Command Bean`. Ví dụ: >`User.java` ```java package com.example.demo; import javax.validation.constraints.Size; import javax.validation.constraints.NotNull; public class User { @NotNull @Size(min=5, message="Username must be at least 5 characters long") private String username; private String password; // constructor, getter, setter } ``` ### 1.4.3. Sử dụng `@Valid` trong `Controller` Trong `RestFul API`, chúng ta sẽ sử dụng `@Valid` để kiểm tra dữ liệu đầu vào của người dùng bằng cách đặt `@Valid` trước `@RequestBody` hoặc trước `@ModelAttribute`. Ví dụ: >`UserController.java` ```java package com.example.demo; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RestController; import jakarta.validation.Valid; @RestController public class UserController { @PostMapping("/user") public String postUser(@Valid @RequestBody User user) { return ... } // Nếu không có lỗi, trả về dữ liệu\ // Nếu có lỗi sẽ trả về BAD_REQUEST với trường thông báo lỗi mặc định của Spring } ``` ### 1.4.4. Tùy chỉnh trường thông báo lỗi trả về Để tùy chỉnh thông báo lỗi cho Invalid dữ liệu, chúng ta tạo một class để tùy chỉnh thông báo lỗi trả về, và 1 class để xử lý lỗi như ở phần `### 3.2.` Trong file `CustomResponseEntityExceptionHandler.java`, `@Override` method để xử lý lỗi cho `MethodArgumentNotValidException` (Bắt buộc phải đúng tên method và tham số truyền vào). ```java ... import org.springframework.web.bind.MethodArgumentNotValidException; @ControllerAdvice public class CustomResponseEntityExceptionHandler extends ResponseEntityExceptionHandler { ... // C1 @Override // Override method này để handle exception lỗi đầu vào của method protected ResponseEntity

Spring: RESTful API trong Spring Boot