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=39 | String courseId |
| 路径参数 | @PathVariable | /detail/010100 | String code |
| JSON 请求体 | @RequestBody | POST /save | CourseForm form |
| 请求头 | @RequestHeader | Authorization | String token |
| 表单/文件 | @RequestParam MultipartFile | POST /upload | MultipartFile 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;
}
@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 本章练习
- 写一个
GET /api/course/detail/{id},返回课程名和简介。
- 写一个
POST /api/course/save,用 @Valid 校验课程名不能为空。
- 故意传错参数,观察 400 和统一错误 JSON,再用前端处理。
下一章进入数据库:JPA 实体、表映射、查询和分页。