第2课：构建完整的 RESTful API

RESTful API 设计原则

REST（Representational State Transfer）是一种 API 设计风格， 它建立在 HTTP 之上，遵循以下原则：

三层架构模式

三层各守自己的边界，越界就是后面难维护的根源：

实战：构建任务管理 API

本课要实现的是一个标准的 CRUD 接口集——创建（Create）、查询（Read）、更新（Update）、删除（Delete）任务。 一共 5 个接口，分 5 步写出来。

步骤1：创建数据模型

数据在网络上用 JSON 传输，在 Java 里则用对象表示。新建 src/main/java/com/sutrasky/hello_spring_boot/model/Task.java：

package com.sutrasky.hello_spring_boot.model;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import java.time.LocalDateTime;

public class Task {

    private Long id;

    @NotBlank(message = "任务标题不能为空")
    @Size(min = 2, max = 100, message = "标题长度必须在2-100之间")
    private String title;

    private String description;
    private boolean completed;
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;

    // 无参构造：Spring 反序列化 JSON 时需要
    public Task() {
        this.createdAt = LocalDateTime.now();
        this.updatedAt = LocalDateTime.now();
    }

    public Task(Long id, String title, String description) {
        this();
        this.id = id;
        this.title = title;
        this.description = description;
    }

    // Getter / Setter
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }

    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }

    public String getDescription() { return description; }
    public void setDescription(String description) { this.description = description; }

    public boolean isCompleted() { return completed; }
    public void setCompleted(boolean completed) { this.completed = completed; }

    public LocalDateTime getCreatedAt() { return createdAt; }
    public LocalDateTime getUpdatedAt() { return updatedAt; }
    public void setUpdatedAt(LocalDateTime updatedAt) { this.updatedAt = updatedAt; }
}

步骤2：创建服务层

新建 service/TaskService.java。 用 @Service 把它交给 Spring 管理，业务逻辑都写在这里：

package com.sutrasky.hello_spring_boot.service;

import com.sutrasky.hello_spring_boot.model.Task;
import org.springframework.stereotype.Service;
import java.time.LocalDateTime;
import java.util.*;
import java.util.concurrent.atomic.AtomicLong;

@Service
public class TaskService {

    // 模拟数据库，使用内存存储
    private final Map<Long, Task> tasks = new HashMap<>();
    private final AtomicLong counter = new AtomicLong();

    public List<Task> getAllTasks() {
        return new ArrayList<>(tasks.values());
    }

    public Task getTaskById(Long id) {
        Task task = tasks.get(id);
        if (task == null) {
            throw new NoSuchElementException("任务不存在，ID: " + id);
        }
        return task;
    }

    public Task createTask(Task task) {
        Long id = counter.incrementAndGet();
        task.setId(id);
        tasks.put(id, task);
        return task;
    }

    public Task updateTask(Long id, Task taskDetails) {
        Task existingTask = getTaskById(id);

        existingTask.setTitle(taskDetails.getTitle());
        existingTask.setDescription(taskDetails.getDescription());
        existingTask.setCompleted(taskDetails.isCompleted());
        existingTask.setUpdatedAt(LocalDateTime.now());

        return existingTask;
    }

    public void deleteTask(Long id) {
        getTaskById(id);   // 不存在就抛异常，交给全局处理器
        tasks.remove(id);
    }

    public List<Task> getTasksByStatus(boolean completed) {
        return tasks.values().stream()
                .filter(task -> task.isCompleted() == completed)
                .toList();
    }
}

步骤3：创建控制器层

新建 controller/TaskController.java。控制器只负责「收请求、给响应」， 业务逻辑一行都不写在这里：

package com.sutrasky.hello_spring_boot.controller;

import com.sutrasky.hello_spring_boot.model.Task;
import com.sutrasky.hello_spring_boot.service.TaskService;
import jakarta.validation.Valid;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.List;

@RestController
@RequestMapping("/api/tasks")
public class TaskController {

    private final TaskService taskService;

    // 构造函数注入（推荐方式）
    public TaskController(TaskService taskService) {
        this.taskService = taskService;
    }

    // 获取所有任务，可按完成状态筛选
    @GetMapping
    public ResponseEntity<List<Task>> getAllTasks(
            @RequestParam(required = false) Boolean completed) {

        List<Task> tasks = (completed != null)
                ? taskService.getTasksByStatus(completed)
                : taskService.getAllTasks();

        return ResponseEntity.ok(tasks);
    }

    // 获取单个任务
    @GetMapping("/{id}")
    public ResponseEntity<Task> getTaskById(@PathVariable Long id) {
        return ResponseEntity.ok(taskService.getTaskById(id));
    }

    // 创建任务
    @PostMapping
    public ResponseEntity<Task> createTask(@Valid @RequestBody Task task) {
        Task created = taskService.createTask(task);
        return ResponseEntity.status(HttpStatus.CREATED).body(created);
    }

    // 更新任务
    @PutMapping("/{id}")
    public ResponseEntity<Task> updateTask(
            @PathVariable Long id,
            @Valid @RequestBody Task taskDetails) {

        return ResponseEntity.ok(taskService.updateTask(id, taskDetails));
    }

    // 删除任务
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteTask(@PathVariable Long id) {
        taskService.deleteTask(id);
        return ResponseEntity.noContent().build();
    }
}

步骤4：全局异常处理

现在访问不存在的任务会抛出异常，返回一坨 500 报错堆栈，很不友好。 新建 exception/GlobalExceptionHandler.java 统一处理：

package com.sutrasky.hello_spring_boot.exception;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.time.LocalDateTime;
import java.util.*;

@RestControllerAdvice
public class GlobalExceptionHandler {

    // Java record：不可变数据载体，一行定义好构造/getter/equals
    public record ErrorResponse(
            LocalDateTime timestamp,
            int status,
            String error,
            String message,
            Map<String, String> validationErrors
    ) {}

    // 资源不存在 -> 404
    @ExceptionHandler(NoSuchElementException.class)
    public ResponseEntity<ErrorResponse> handleNotFound(NoSuchElementException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(new ErrorResponse(
                LocalDateTime.now(),
                HttpStatus.NOT_FOUND.value(),
                "Not Found",
                ex.getMessage(),
                null
        ));
    }

    // 校验失败 -> 400，并把每个字段的错误原因列出来
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidationErrors(
            MethodArgumentNotValidException ex) {

        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getAllErrors().forEach(error -> {
            String field = ((FieldError) error).getField();
            errors.put(field, error.getDefaultMessage());
        });

        return ResponseEntity.badRequest().body(new ErrorResponse(
                LocalDateTime.now(),
                HttpStatus.BAD_REQUEST.value(),
                "Validation Failed",
                "请求参数验证失败",
                errors
        ));
    }

    // 兜底：其他未预料异常 -> 500
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGeneralError(Exception ex) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(new ErrorResponse(
                LocalDateTime.now(),
                HttpStatus.INTERNAL_SERVER_ERROR.value(),
                "Internal Server Error",
                "服务器内部错误：" + ex.getMessage(),
                null
        ));
    }
}

三个处理方法的分工，一张对照表记住：

NoSuchElementException

资源不存在 → 404 Not Found，message 用异常自带的说明

MethodArgumentNotValidException

校验不通过 → 400 Validation Failed，validationErrors 逐字段列出原因

Exception（兜底）

其余未预料的异常 → 500 Internal Server Error

步骤5：补上校验依赖

在 pom.xml 的 <dependencies> 里加：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

运行并测试

mvnw.cmd spring-boot:run

# 1. 创建任务
curl -X POST http://localhost:8081/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "学习 Spring Boot", "description": "完成第2课"}'

# 2. 获取所有任务
curl http://localhost:8081/api/tasks

# 3. 获取单个任务
curl http://localhost:8081/api/tasks/1

# 4. 更新任务
curl -X PUT http://localhost:8081/api/tasks/1 \
  -H "Content-Type: application/json" \
  -d '{"title": "学习 Spring Boot", "description": "已完成", "completed": true}'

# 5. 删除任务
curl -X DELETE http://localhost:8081/api/tasks/1

# 6. 按状态筛选
curl "http://localhost:8081/api/tasks?completed=true"

# 1. 创建任务
http POST :8081/api/tasks title="学习 Spring Boot" description="完成第2课"

# 2. 获取所有任务
http GET :8081/api/tasks

# 3. 获取单个任务
http GET :8081/api/tasks/1

# 4. 更新任务
http PUT :8081/api/tasks/1 title="学习 Spring Boot" description="已完成" completed:=true

# 5. 删除任务
http DELETE :8081/api/tasks/1

三个必做的验证

好的 API 不只「能用」，还要「用错时给出正确反馈」。逐个验证：

# 验证1：标题为空 -> 应该是 400 + 字段错误信息
curl -X POST http://localhost:8081/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "", "description": "测试"}'

# 验证2：标题只有1个字（@Size min=2）-> 应该是 400
curl -X POST http://localhost:8081/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "短", "description": "测试"}'

# 验证3：访问不存在的任务 -> 应该是 404 而不是 500
curl http://localhost:8081/api/tasks/999

知识检验

推荐阅读（按优先级）

1. Spring 官方：Building a RESTful Web Service —— 本课的主参考，官方权威
2. RESTful API 设计最佳实践 —— 系统讲设计规范
3. Baeldung：Bean Validation —— 校验注解大全
4. 本工作区：Spring Boot 核心注解速查表 —— 本课用到的 9 个注解都在里面有表格
5. 本工作区：HTTP 方法与状态码速查表

课后挑战（做完再往下学）