Spring MVC 请求处理与参数绑定指南

本文聚焦 Spring MVC 在 Controller 层的核心能力：请求路由映射、常见参数接收、JSON 绑定以及文件上传处理，帮助你把“HTTP 请求”稳定地映射到“Controller 方法”。

第一章请求路由映射

1.1 统一路由映射：`@RequestMapping`

在实际开发中，同一个 Controller 往往处理同一类资源的操作（如“部门”的增删改查），它们的路由前缀通常相同。为了避免在每个方法上重复编写相同路径，可以将公共前缀提取到类级别的 @RequestMapping。

@RequestMapping("/depts")
@RestController
public class DeptController {

    @GetMapping
    public Result list() {
        return Result.success();
    }

    @DeleteMapping
    public Result delete(Integer id) {
        return Result.success();
    }
}

这样做的价值在于：

让 Controller 管理的资源边界更清晰
减少重复路径声明
更符合 RESTful 风格

1.2 RESTful 风格的 Spring MVC 写法

@RestController
@RequestMapping("/depts")
public class DeptController {

    @GetMapping
    public Result list() {
        return Result.success();
    }

    @GetMapping("/{id}")
    public Result getById(@PathVariable Integer id) {
        return Result.success();
    }

    @PostMapping
    public Result save(@RequestBody Dept dept) {
        return Result.success();
    }

    @PutMapping("/{id}")
    public Result update(@PathVariable Integer id, @RequestBody Dept dept) {
        dept.setId(id);
        return Result.success();
    }

    @DeleteMapping("/{id}")
    public Result delete(@PathVariable Integer id) {
        return Result.success();
    }
}

第二章简单参数接收

2.1 通过 `HttpServletRequest` 获取参数

这是最传统的 Java Web 参数获取方式，通过注入 HttpServletRequest 并调用 getParameter 获取参数值。

@DeleteMapping
public Result delete(HttpServletRequest request) {
    String deptIdStr = request.getParameter("id");
    Integer deptId = Integer.parseInt(deptIdStr);
    return Result.success();
}

这种方式的特点是：

与底层 Servlet API 贴得更近
需要手动做类型转换
在 Spring MVC 中通常不作为首选

2.2 通过 `@RequestParam` 绑定参数

当前端参数名与后端方法形参名不一致时，可以使用 @RequestParam 做显式映射。

@DeleteMapping
public Result delete(@RequestParam("id") Integer deptId) {
    return Result.success();
}

常见属性：

required = true：默认必须传递
required = false：允许不传递
defaultValue = "0"：设置默认值

2.3 参数名一致时直接接收

如果前端参数名与后端方法形参名一致，通常可以省略注解直接接收：

@GetMapping("/search")
public Result search(String name, Integer status) {
    return Result.success();
}

这也是最常见、最简洁的写法。

第三章数组、集合与路径参数

3.1 数组参数接收

当前端传递多个同名参数时，Spring MVC 可以直接绑定到数组：

// 请求：/delete?ids=1&ids=2&ids=3
@DeleteMapping("/batch")
public Result deleteBatch(Integer[] ids) {
    return Result.success();
}

只需保证参数名与数组变量名一致即可。

3.2 集合参数接收

如果使用 List 等集合类型接收，通常需要加上 @RequestParam：

// 请求：/delete?ids=1&ids=2&ids=3
@DeleteMapping("/batchList")
public Result deleteBatchList(@RequestParam List<Integer> ids) {
    return Result.success();
}

这是因为 Spring 在没有注解时，常把复杂类型当作 POJO 对象处理，而 List 不是普通的 JavaBean。

3.3 路径参数接收

当参数直接写在 URL 路径中时，可以使用 @PathVariable 获取。

@GetMapping("/{id}")
public Result getInfo(@PathVariable("id") Integer deptId) {
    return Result.success();
}

这类写法更符合 RESTful 中“资源路径表达资源标识”的思路。

第四章 JSON 请求体绑定

当前端通过 POST 或 PUT 请求在请求体中传递 JSON 时，后端接收通常需要满足两个条件：

使用实体对象接收，并保证 JSON 键名与对象属性名一致。
在参数上添加 @RequestBody，让 Spring 把 JSON 反序列化为 Java 对象。

@PostMapping
public Result add(@RequestBody Dept dept) {
    return Result.success();
}

这一能力的本质是：

Spring MVC 识别 @RequestBody
通过消息转换器（如 Jackson）完成 JSON 与对象之间的转换

第五章文件上传处理

在 Spring Boot / Spring MVC 中，文件上传通常使用 MultipartFile 接收前端发送的 multipart/form-data 数据。

5.1 常见 API

multipartFile.getOriginalFilename()：获取原始文件名
multipartFile.transferTo(File dest)：把临时文件转存到目标位置

5.2 示例代码

@PostMapping("/upload")
public Result upload(String name, Integer age, MultipartFile image) throws IOException {
    String originalFilename = image.getOriginalFilename();

    String ext = originalFilename.substring(originalFilename.lastIndexOf("."));
    String fileName = UUID.randomUUID().toString() + ext;

    image.transferTo(new File("C:/Users/Desktop/images/" + fileName));
    return Result.success();
}

上传时建议注意：

给文件生成唯一名称，避免覆盖
校验文件大小、类型与后缀
不要把上传目录写死在不可维护的位置
生产环境通常接入对象存储，而不是直接落本地磁盘

5.3 文件大小限制配置

Spring Boot 默认上传文件最大大小为 1MB。如果文件超过该限制，可以在 application.yml 中调整：

spring:
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 100MB

本文小结

使用 @RequestMapping、@GetMapping、@PostMapping 等注解定义清晰路由。
简单参数优先使用直接接收或 @RequestParam。
路径参数使用 @PathVariable，JSON 请求体使用 @RequestBody。
数组与集合参数的绑定规则并不完全相同。
文件上传是 Spring MVC 参数绑定的一种特殊场景，重点在接收、校验与存储。