Spring 学习笔记 11：REST API 基础——把 Service 暴露成接口

package com.example.library.web;

import com.example.library.domain.Book;
import com.example.library.domain.BookStatus;
import com.example.library.dto.BookResponse;
import com.example.library.dto.BookTitleDto;
import com.example.library.service.BookService;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PatchMapping;
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.RequestParam;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/api/books")
public class BookController {

    private final BookService bookService;

    public BookController(BookService bookService) {
        this.bookService = bookService;
    }

    @GetMapping
    public Page<BookTitleDto> list(@RequestParam(name = "keyword", required = false) String keyword,
                                   Pageable pageable) {
        return bookService.searchTitles(keyword, pageable);
    }

    @GetMapping("/{id}")
    public BookResponse get(@PathVariable Long id) {
        return bookService.toResponse(bookService.findById(id));
    }

    @GetMapping("/summaries")
    public List<BookTitleDto> summaries() {
        return bookService.availableSummaries();
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public BookResponse add(@RequestBody CreateBookRequest request) {
        Book book = bookService.add(request.title(), request.author());
        return bookService.toResponse(book);
    }

    @PatchMapping("/{id}/status")
    public BookResponse changeStatus(@PathVariable Long id, @RequestBody ChangeStatusRequest request) {
        bookService.markStatus(id, request.status());
        return bookService.toResponse(bookService.findById(id));
    }

    public record CreateBookRequest(String title, String author) {
    }

    public record ChangeStatusRequest(BookStatus status) {
    }
}

package com.example.library.dto;

import com.example.library.domain.Book;
import com.example.library.domain.BookStatus;

/** 对外返回的图书表示：不用把实体直接暴露给客户端 */
public record BookResponse(Long id, String title, String author, BookStatus status, String categoryName) {

    public static BookResponse of(Book book) {
        String categoryName = book.getCategory() == null ? null : book.getCategory().getName();
        return new BookResponse(book.getId(), book.getTitle(), book.getAuthor(), book.getStatus(), categoryName);
    }
}

package com.example.library.dto;

/** DTO 构造表达式需要它在 JPQL 里写成全限定类名（见第 03 篇） */
public record BookTitleDto(String title, String author) {
}

package com.example.library.web;

import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import java.util.NoSuchElementException;

/** REST 接口的统一异常处理：返回 RFC 7807 风格的问题详情 */
@RestControllerAdvice(assignableTypes = BookController.class)
public class ApiExceptionHandler {

    @ExceptionHandler(NoSuchElementException.class)
    public ProblemDetail handleNotFound(NoSuchElementException ex) {
        ProblemDetail detail = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
        detail.setTitle("资源不存在");
        return detail;
    }

    @ExceptionHandler(IllegalArgumentException.class)
    public ProblemDetail handleBadRequest(IllegalArgumentException ex) {
        ProblemDetail detail = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, ex.getMessage());
        detail.setTitle("请求参数不合法");
        return detail;
    }

    @ExceptionHandler(IllegalStateException.class)
    public ProblemDetail handleConflict(IllegalStateException ex) {
        ProblemDetail detail = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, ex.getMessage());
        detail.setTitle("当前状态不允许该操作");
        return detail;
    }
}

{
  "type": "about:blank",
  "title": "资源不存在",
  "status": 404,
  "detail": "找不到图书：999"
}

package com.example.library.web;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

/** 端到端：真实上下文 + 真实拦截器 + 真实数据库 */
@SpringBootTest
@AutoConfigureMockMvc
class BookControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    @DisplayName("GET /api/books 返回分页 JSON，并且不被登录拦截器拦下")
    void listsBooks() throws Exception {
        mockMvc.perform(get("/api/books").param("size", "3"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.content").isArray())
                .andExpect(jsonPath("$.totalElements").isNumber());
    }

    @Test
    @DisplayName("POST /api/books 返回 201 与新建的图书")
    void createsBook() throws Exception {
        mockMvc.perform(post("/api/books")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                 {"title":"重构","author":"Martin Fowler"}
                                 """))
                .andExpect(status().isCreated())
                .andExpect(jsonPath("$.title").value("重构"))
                .andExpect(jsonPath("$.id").isNumber());
    }

    @Test
    @DisplayName("查询不存在的图书返回 404 与 ProblemDetail")
    void returnsProblemDetailForMissingBook() throws Exception {
        mockMvc.perform(get("/api/books/999999"))
                .andExpect(status().isNotFound())
                .andExpect(jsonPath("$.title").value("资源不存在"))
                .andExpect(jsonPath("$.status").value(404));
    }
}

@WebMvcTest(BookController.class)
class BookControllerSliceTest {

    @Autowired
    private MockMvc mockMvc;

    @MockitoBean
    private BookService bookService;

    @MockitoBean
    private LoginInterceptor loginInterceptor;

    @MockitoBean
    private AdminInterceptor adminInterceptor;

    @MockitoBean
    private TimingInterceptor timingInterceptor;

    @BeforeEach
    void allowAllRequestsThrough() throws Exception {
        // Mock 出来的拦截器 preHandle 默认返回 false，会让所有请求中断，必须显式放行
        given(loginInterceptor.preHandle(any(), any(), any())).willReturn(true);
        given(adminInterceptor.preHandle(any(), any(), any())).willReturn(true);
        given(timingInterceptor.preHandle(any(), any(), any())).willReturn(true);
    }

    @Test
    @DisplayName("切片测试：返回图书 JSON")
    void returnsBookJson() throws Exception {
        Book book = new Book("重构", "Martin Fowler");
        given(bookService.findById(1L)).willReturn(book);
        given(bookService.toResponse(book)).willReturn(
                new BookResponse(1L, "重构", "Martin Fowler", BookStatus.AVAILABLE, "技术"));

        mockMvc.perform(get("/api/books/1"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.title").value("重构"))
                .andExpect(jsonPath("$.categoryName").value("技术"));
    }
}