第9章 Controller 与 JSON

第 9 节 / 共 17 节 课程:前后端穿透

Controller 是后端的门口。它决定一个 URL 由哪个方法处理、参数从哪里来、返回什么。门口没管好,后面的业务再强也会被脏参数打穿。

9.1 @RestController 做了什么

@RestController 等于 @Controller + @ResponseBody:方法返回的对象会被 Jackson 转成 JSON,而不是去找一个页面模板。

@RestController
@RequestMapping("/api/course")
public class CourseController {
 
    @GetMapping("/list")
    public Result<List<Course>> list() {
        return Result.ok(courseService.findAll());
    }
}

如果只写 @Controller,返回 List 通常会被当成视图名,报 404 或模板找不到。

9.2 URL 映射

注解位置例子说明
@RequestMapping类/方法/api/course统一前缀
@GetMapping方法/list查询
@PostMapping方法/save新增
@PutMapping方法/update整体修改
@DeleteMapping方法/{id}删除

同一个路径可以用不同方法区分:GET /course/39 查询,DELETE /course/39 删除。不要用 GET /delete?id=39,爬虫或预取可能误删数据。

9.3 参数从哪里来

场景注解示例 URL代码
查询参数@RequestParam/list?courseId=39String courseId
路径参数@PathVariable/detail/010100String code
JSON 请求体@RequestBodyPOST /saveCourseForm form
请求头@RequestHeaderAuthorizationString token
表单/文件@RequestParam MultipartFilePOST /uploadMultipartFile file
@GetMapping("/detail/{code}")
public Result<Chapter> detail(@PathVariable String code) {
    return Result.ok(chapterService.getByCode(code));
}
 
@GetMapping("/list")
public Result<List<Chapter>> list(@RequestParam String courseId) {
    return Result.ok(chapterService.findByCourse(courseId));
}

@RequestParam 默认必填;可写成 @RequestParam(defaultValue = "1") int page。参数类型是 int 时,传了非数字会直接 400,前端要能处理。

9.4 接收 JSON

public class CourseForm {
    @NotBlank(message = "课程名不能为空")
    private String name;
 
    @Size(max = 20, message = "课程名最多 20 字")
    private String bref;
 
    // getter / setter
}
 
@PostMapping("/save")
public Result<Long> save(@Valid @RequestBody CourseForm form) {
    return Result.ok(courseService.save(form));
}

@RequestBody 要求请求头 Content-Type: application/json。前端 axios 传对象时默认就是 JSON;如果后端用 @RequestParam 接,就会拿不到。

9.5 参数校验与统一错误

校验失败时 Spring 会抛 MethodArgumentNotValidException。用 @RestControllerAdvice 统一转成 JSON,前端就不用解析一大段异常。

@RestControllerAdvice
public class GlobalExceptionHandler {
 
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<Void> handleValid(MethodArgumentNotValidException e) {
        String msg = e.getBindingResult().getFieldErrors().stream()
        .map(FieldError::getDefaultMessage)
        .findFirst()
        .orElse("参数不合法");
        return Result.fail(msg);
    }
 
    @ExceptionHandler(Exception.class)
    public Result<Void> handleAll(Exception e) {
        e.printStackTrace();
        return Result.fail("服务器开小差了,请稍后重试");
    }
}
全局异常处理不要把堆栈返回给用户。日志里保留完整堆栈,响应里只给可读提示和错误码。

9.6 JSON 的形状

Jackson 默认把 getter 暴露成字段。常见问题:

问题表现处理
日期是时间戳前端拿到 1699999999000配置 date-format 或 @JsonFormat
null 字段消失前端拿不到 key配置 NON_NULL 策略
懒加载报错返回时序列化代理失败用 DTO,不直接返回 Entity
字段名不对前端要 courseId,后端给 id@JsonProperty 或 DTO
spring:
  jackson:
    date-format: yyyy-MM-dd HH:mm:ss
    time-zone: Asia/Shanghai
    default-property-inclusion: non_null

更稳的做法是定义响应 DTO,只暴露前端需要的字段。Entity 是数据库结构,不应该直接当 API 契约。

9.7 一个完整的 Controller

@RestController
@RequestMapping("/api/chapter")
public class ChapterController {
 
    private final ChapterService service;
 
    public ChapterController(ChapterService service) {
        this.service = service;
    }
 
    @GetMapping("/list")
    public Result<List<ChapterBrief>> list(@RequestParam String courseId) {
        return Result.ok(service.listByCourse(courseId));
    }
 
    @GetMapping("/detail/{code}")
    public Result<ChapterDetail> detail(@PathVariable String code) {
        return Result.ok(service.detail(code));
    }
 
    @PostMapping("/save")
    public Result<Long> save(@Valid @RequestBody ChapterForm form) {
        return Result.ok(service.save(form));
    }
}

9.8 本章练习

  1. 写一个 GET /api/course/detail/{id},返回课程名和简介。
  2. 写一个 POST /api/course/save,用 @Valid 校验课程名不能为空。
  3. 故意传错参数,观察 400 和统一错误 JSON,再用前端处理。

下一章进入数据库:JPA 实体、表映射、查询和分页。