总览
1.查询参数（Query Parameters）
1.1 前端请求（URL 拼接）
GET /api/users?page=1&size=10&keyword=张三
- 参数直接拼在 URL ? 后面
- 多个参数用 & 连接
- 适用于 GET 请求（也可用于 POST，但不推荐）
1.2 后端接收方式（@RequestParam）
@GetMapping("/users")
public List<User> getUsers(@RequestParam(defaultValue = "1") int page,@RequestParam(defaultValue = "10") int size,@RequestParam(required = false) String keyword
) {// ...
}
1.3 适用场景
- 分页查询
- 搜索过滤
- 简单配置类参数
1.4 注意
- 不适合传敏感数据（会被日志记录）
- URL 长度有限制（一般 < 2048 字符
2.路径参数（Path Variable）
2.1 前端请求（URL 路径中嵌入）
GET /api/users/123
DELETE /api/orders/ORD20251114
- 参数作为 URL 路径的一部分
- 通常表示“资源 ID”
2.2 后端接收方式（@PathVariable）
@GetMapping("/users/{id}")
public User getUserById(@PathVariable Long id) {return userService.findById(id);
}@DeleteMapping("/orders/{orderNo}")
public void deleteOrder(@PathVariable String orderNo) {orderService.delete(orderNo);
}
2.3 适用场景
- 获取/删除/更新某个具体资源
- RESTful 风格 API
2.4 注意
- 路径参数不能省略（除非用正则或可选路径，但复杂）
- 类型需匹配（如 Long 对应数字字符串
3.表单数据（Form Data / x-www-form-urlencoded）
3.1 前端请求（body 为 key=value&...）
POST /api/login
Content-Type: application/x-www-form-urlencodedusername=admin&password=123456
数据在请求体（body）中
- 格式类似 URL 查询字符串
- 浏览器原生
3.2 后端接收方式（@RequestParam）
@PostMapping("/login")
public Result<?> login(@RequestParam String username,@RequestParam String password
) {// ...
}
3.3 适用场景
- 传统表单登录
- 简单数据提交（无嵌套结构）
3.4 注意
- 不支持复杂对象（如 { user: { name: "a" } }）
- Spring 会自动解析 x-www-form-urlencoded 到 @RequestParam
4.JSON 数据（Request Body）
4.1 前端请求（body 为 JSON）
POST /api/orders
Content-Type: application/json{"goodsId": 1001,"count": 2,"address": {"province": "广东","city": "深圳"}
}
- 最常见的现代 API 交互方式
- 支持嵌套对象、数组等复杂结构
4.2 后端接收方式（@RequestBody + DTO）
@PostMapping("/orders")
public Result<?> createOrder(@RequestBody CreateOrderRequest req) {// req.getGoodsId(), req.getAddress()...
}// DTO 类
public class CreateOrderRequest {private Long goodsId;private Integer count;private Address address;// getter/setter
}
4.3 适用场景
- 创建/更新复杂资源（如订单、用户资料）
- 前后端分离项目（Vue/React + Spring Boot）
- 微信支付、下单等业务接口
4.4 注意
- 必须设置 Content-Type: application/json
- 字段名需前后端一致（可用 @JsonProperty 映射）
- 推荐加 @Valid 做参数校验
5.文件上传（Multipart Form Data）
5.1 前端请求模样（multipart/form-data）
POST /api/upload/avatar
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="userId"123
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="avatar.jpg"
Content-Type: image/jpeg(二进制文件内容...)
------WebKitFormBoundary7MA4YWxkTrZu0gW--
5.2 后端接收方式（@RequestParam MultipartFile）
@PostMapping("/upload/avatar")
public Result<?> uploadAvatar(@RequestParam Long userId,@RequestParam MultipartFile file
) {// 保存文件...
}
5.3 适用场景
- 头像上传
- 附件提交
- 富文本编辑器图片上传
5.4注意
- 不能用 @RequestBody
- 需配置文件大小限制（spring.servlet.multipart.max-file-size）