Xây REST API với Spring Boot

03-rest-api/
  pom.xml
  src/main/java/dev/canhdominich/boot/rest/
    RestApplication.java        @SpringBootApplication
    Course.java                 record tài nguyên (id, tiêu đề, giá)
    CourseRequest.java          record dữ liệu vào, có ràng buộc Bean Validation
    PageResponse.java           record một trang kết quả
    CourseNotFoundException.java ngoại lệ nghiệp vụ
    CourseStore.java            kho dữ liệu trong bộ nhớ
    CourseController.java       các endpoint /api/courses
    ApiExceptionHandler.java    @RestControllerAdvice trả ProblemDetail
    RestDemo.java               khởi động ứng dụng, gửi yêu cầu HTTP và in kết quả

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.1</version>
        <relativePath/>
    </parent>

    <groupId>dev.canhdominich.javabackend</groupId>
    <artifactId>boot-rest-api</artifactId>
    <version>1.0.0</version>
    <name>Spring Boot - REST API</name>

    <properties>
        <java.version>17</java.version>
        <main.class>dev.canhdominich.boot.rest.RestDemo</main.class>
    </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-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <configuration>
                    <executable>java</executable>
                    <arguments>
                        <argument>-classpath</argument>
                        <classpath/>
                        <argument>${main.class}</argument>
                    </arguments>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

package dev.canhdominich.boot.rest;

public record Course(Long id, String title, int price) {
}

package dev.canhdominich.boot.rest;

import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;

public record CourseRequest(
        @NotBlank @Size(max = 60) String title,
        @Min(0) int price) {
}

package dev.canhdominich.boot.rest;

import java.util.List;

public record PageResponse<T>(List<T> items, int page, int size, long total) {
}

package dev.canhdominich.boot.rest;

public class CourseNotFoundException extends RuntimeException {

    public CourseNotFoundException(long id) {
        super("Course " + id + " does not exist");
    }
}

package dev.canhdominich.boot.rest;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.ConcurrentSkipListMap;
import java.util.concurrent.atomic.AtomicLong;
import org.springframework.stereotype.Component;

@Component
public class CourseStore {

    private final Map<Long, Course> courses = new ConcurrentSkipListMap<>();
    private final AtomicLong ids = new AtomicLong();

    public Course create(CourseRequest request) {
        Course course = new Course(ids.incrementAndGet(), request.title(), request.price());
        courses.put(course.id(), course);
        return course;
    }

    public Optional<Course> find(long id) {
        return Optional.ofNullable(courses.get(id));
    }

    public Optional<Course> replace(long id, CourseRequest request) {
        if (!courses.containsKey(id)) {
            return Optional.empty();
        }
        Course course = new Course(id, request.title(), request.price());
        courses.put(id, course);
        return Optional.of(course);
    }

    public boolean delete(long id) {
        return courses.remove(id) != null;
    }

    public PageResponse<Course> page(int page, int size) {
        List<Course> all = new ArrayList<>(courses.values());
        int from = Math.min(page * size, all.size());
        int to = Math.min(from + size, all.size());
        return new PageResponse<>(all.subList(from, to), page, size, all.size());
    }

    public void clear() {
        courses.clear();
        ids.set(0);
    }
}

package dev.canhdominich.boot.rest;

import jakarta.validation.Valid;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import java.net.URI;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
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.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/courses")
public class CourseController {

    private final CourseStore store;

    public CourseController(CourseStore store) {
        this.store = store;
    }

    @GetMapping
    public PageResponse<Course> list(@RequestParam(defaultValue = "0") @Min(0) int page,
            @RequestParam(defaultValue = "5") @Min(1) @Max(50) int size) {
        return store.page(page, size);
    }

    @GetMapping("/{id}")
    public Course one(@PathVariable long id) {
        return store.find(id).orElseThrow(() -> new CourseNotFoundException(id));
    }

    @PostMapping
    public ResponseEntity<Course> create(@Valid @RequestBody CourseRequest request) {
        Course created = store.create(request);
        return ResponseEntity.created(URI.create("/api/courses/" + created.id())).body(created);
    }

    @PutMapping("/{id}")
    public Course replace(@PathVariable long id, @Valid @RequestBody CourseRequest request) {
        return store.replace(id, request).orElseThrow(() -> new CourseNotFoundException(id));
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> delete(@PathVariable long id) {
        if (!store.delete(id)) {
            throw new CourseNotFoundException(id);
        }
        return ResponseEntity.noContent().build();
    }
}

package dev.canhdominich.boot.rest;

import java.util.Map;
import java.util.TreeMap;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

@RestControllerAdvice
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(CourseNotFoundException.class)
    public ProblemDetail notFound(CourseNotFoundException e) {
        return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, e.getMessage());
    }

    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(MethodArgumentNotValidException e, HttpHeaders headers, HttpStatusCode status, WebRequest request) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, "Request validation failed");
        Map<String, String> errors = new TreeMap<>();
        e.getBindingResult().getFieldErrors().forEach(error -> errors.put(error.getField(), error.getDefaultMessage()));
        problem.setProperty("errors", errors);
        return handleExceptionInternal(e, problem, headers, status, request);
    }
}

package dev.canhdominich.boot.rest;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class RestApplication {

    public static void main(String[] args) {
        SpringApplication.run(RestApplication.class, args);
    }
}

package dev.canhdominich.boot.rest;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.web.server.context.WebServerApplicationContext;
import org.springframework.context.ConfigurableApplicationContext;

public class RestDemo {

    public static void main(String[] args) throws Exception {
        run();
    }

    public static List<String> run() throws Exception {
        List<String> lines = new ArrayList<>();
        SpringApplication application = new SpringApplication(RestApplication.class);
        application.setDefaultProperties(Map.of("server.port", "0", "spring.main.banner-mode", "off", "logging.level.root", "OFF"));
        try (ConfigurableApplicationContext context = application.run()) {
            int port = ((WebServerApplicationContext) context).getWebServer().getPort();
            Client client = new Client(port, lines);
            client.send("POST", "/api/courses", "application/json", "{\"title\":\"Spring Boot\",\"price\":100}");
            client.send("POST", "/api/courses", "application/json", "{\"title\":\"\",\"price\":-1}");
            client.send("POST", "/api/courses", "application/json", "{\"title\":\"Extra field ignored\",\"price\":5,\"unknown\":true}");
            client.send("POST", "/api/courses", "application/json", "{\"title\":");
            client.send("POST", "/api/courses", "text/plain", "Spring Boot");
            for (int i = 4; i <= 12; i++) {
                client.quiet("POST", "/api/courses", "application/json", "{\"title\":\"Course " + i + "\",\"price\":" + i + "}");
            }
            client.send("GET", "/api/courses/1", null, null);
            client.send("GET", "/api/courses/99", null, null);
            client.send("GET", "/api/courses?page=1&size=5", null, null);
            client.send("GET", "/api/courses?size=0", null, null);
            client.send("GET", "/api/courses?size=abc", null, null);
            client.send("PUT", "/api/courses/1", "application/json", "{\"title\":\"Spring Boot 4\",\"price\":150}");
            client.send("PUT", "/api/courses/99", "application/json", "{\"title\":\"x\",\"price\":1}");
            client.send("DELETE", "/api/courses/1", null, null);
            client.send("DELETE", "/api/courses/1", null, null);
            client.send("PATCH", "/api/courses/2", "application/json", "{}");
            client.send("GET", "/api/courses/2", "Accept: application/xml", null);
        }
        return lines;
    }

    static final class Client {

        private final int port;
        private final List<String> lines;
        private final HttpClient http = HttpClient.newHttpClient();

        Client(int port, List<String> lines) {
            this.port = port;
            this.lines = lines;
        }

        void quiet(String method, String path, String type, String body) throws Exception {
            request(method, path, type, body);
        }

        void send(String method, String path, String type, String body) throws Exception {
            HttpResponse<String> response = request(method, path, type, body);
            StringBuilder out = new StringBuilder(method + " " + path + (body == null ? "" : " " + body) + " -> " + response.statusCode());
            response.headers().firstValue("Content-Type").ifPresent(contentType -> out.append(" ").append(contentType.split(";")[0]));
            response.headers().firstValue("Location").ifPresent(location -> out.append(" Location: ").append(location));
            response.headers().firstValue("Allow").ifPresent(allow -> out.append(" Allow: ").append(String.join(", ", new java.util.TreeSet<>(List.of(allow.split(", "))))));
            String text = response.body().replaceAll("\"instance\":\"[^\"]*\",?", "").replaceAll(",}", "}").replaceAll("\\s+", " ").trim();
            if (!text.isEmpty()) {
                out.append(" | ").append(text);
            }
            System.out.println(out);
            lines.add(out.toString());
        }

        private HttpResponse<String> request(String method, String path, String type, String body) throws Exception {
            HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create("http://127.0.0.1:" + port + path));
            if (type != null && type.startsWith("Accept: ")) {
                builder.header("Accept", type.substring("Accept: ".length()));
            } else if (type != null) {
                builder.header("Content-Type", type);
            }
            builder.method(method, body == null ? HttpRequest.BodyPublishers.noBody() : HttpRequest.BodyPublishers.ofString(body));
            return http.send(builder.build(), HttpResponse.BodyHandlers.ofString());
        }
    }
}

POST /api/courses {"title":"Spring Boot","price":100} -> 201 application/json Location: /api/courses/1 | {"id":1,"title":"Spring Boot","price":100}
POST /api/courses {"title":"","price":-1} -> 400 application/problem+json | {"detail":"Request validation failed","status":400,"title":"Bad Request","errors":{"price":"must be greater than or equal to 0","title":"must not be blank"}}
POST /api/courses {"title":"Extra field ignored","price":5,"unknown":true} -> 201 application/json Location: /api/courses/2 | {"id":2,"title":"Extra field ignored","price":5}
POST /api/courses {"title": -> 400 application/problem+json | {"detail":"Failed to read request","status":400,"title":"Bad Request"}
POST /api/courses Spring Boot -> 415 application/problem+json | {"detail":"Content-Type 'text/plain;charset=UTF-8' is not supported.","status":415,"title":"Unsupported Media Type"}
GET /api/courses/1 -> 200 application/json | {"id":1,"title":"Spring Boot","price":100}
GET /api/courses/99 -> 404 application/problem+json | {"detail":"Course 99 does not exist","status":404,"title":"Not Found"}
GET /api/courses?page=1&size=5 -> 200 application/json | {"items":[{"id":6,"title":"Course 7","price":7},{"id":7,"title":"Course 8","price":8},{"id":8,"title":"Course 9","price":9},{"id":9,"title":"Course 10","price":10},{"id":10,"title":"Course 11","price":11}],"page":1,"size":5,"total":11}
GET /api/courses?size=0 -> 400 application/problem+json | {"detail":"Validation failure","status":400,"title":"Bad Request"}
GET /api/courses?size=abc -> 400 application/problem+json | {"detail":"Failed to convert 'size' with value: 'abc'","status":400,"title":"Bad Request"}
PUT /api/courses/1 {"title":"Spring Boot 4","price":150} -> 200 application/json | {"id":1,"title":"Spring Boot 4","price":150}
PUT /api/courses/99 {"title":"x","price":1} -> 404 application/problem+json | {"detail":"Course 99 does not exist","status":404,"title":"Not Found"}
DELETE /api/courses/1 -> 204
DELETE /api/courses/1 -> 404 application/problem+json | {"detail":"Course 1 does not exist","status":404,"title":"Not Found"}
PATCH /api/courses/2 {} -> 405 application/problem+json Allow: DELETE, GET, PUT | {"detail":"Method 'PATCH' is not supported.","status":405,"title":"Method Not Allowed"}
GET /api/courses/2 -> 406 application/problem+json | {"detail":"Acceptable representations: [application/json, application/*+json].","status":406,"title":"Not Acceptable"}