接口参照

总览

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）