HTTP与SpringBoot参数交互全指南

一、HTTP请求基础类型

1.1 主要请求方式对比

pie
    title HTTP请求方式使用率
    "GET" : 45
    "POST" : 35
    "PUT" : 10
    "DELETE" : 5
    "其他" : 5

1.2 请求特征分析

方法	安全性	幂等性	请求体	典型场景
GET	否	是	无	查询操作
POST	否	否	有	创建资源/复杂查询
PUT	否	是	有	全量更新
PATCH	否	否	有	部分更新
DELETE	否	是	无	删除资源

二、SpringBoot参数接收方式

2.1 接收方式矩阵

graph TD
    A[请求参数] --> B[URL参数]
    A --> C[表单数据]
    A --> D[JSON数据]
    A --> E[路径变量]
    B --> F[@RequestParam]
    C --> G[@ModelAttribute]
    D --> H[@RequestBody]
    E --> I[@PathVariable]

2.2 核心注解对比

注解	适用场景	默认必传	支持类型
@RequestParam	URL查询参数	是	基本类型/简单对象
@PathVariable	RESTful路径参数	是	基本类型
@RequestBody	JSON/XML请求体	是	复杂对象
@ModelAttribute	表单数据/多部分表单	否	对象/文件上传
@RequestHeader	请求头参数	否	基本类型

三、GET请求处理

3.1 基础参数接收

@GetMapping("/search")
public ResponseEntity<?> searchProducts(
    @RequestParam String keyword,
    @RequestParam(required = false, defaultValue = "1") Integer page,
    @RequestParam(required = false, defaultValue = "10") Integer size) {
    // 实现逻辑
}

3.2 参数映射对象

@Data // Lombok注解
public class SearchCriteria {
    private String keyword;
    private Integer page = 1;
    private Integer size = 10;
}

@GetMapping("/search")
public ResponseEntity<?> searchProducts(@ModelAttribute SearchCriteria criteria) {
    // 自动绑定参数到对象
}

四、POST请求处理

4.1 JSON数据处理

@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody User user) {
    // 处理JSON格式的User对象
    return ResponseEntity.ok(userService.save(user));
}

4.2 表单数据处理

@PostMapping(value = "/login", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
public String login(@ModelAttribute LoginForm form) {
    // 处理application/x-www-form-urlencoded数据
}

五、复杂参数处理

5.1 嵌套对象接收

@Data
public class OrderCreateDTO {
    private String orderNo;
    private List<OrderItem> items;
    private UserAddress address;
}

@PostMapping("/orders")
public Order createOrder(@RequestBody OrderCreateDTO dto) {
    // 处理嵌套对象
}

5.2 多部分文件上传

@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public String handleFileUpload(
    @RequestPart MultipartFile file,
    @RequestPart FileMetaData meta) {
    // 处理文件上传
}

六、RESTful风格参数

6.1 路径变量使用

@GetMapping("/products/{id}")
public Product getProduct(@PathVariable Long id) {
    // 获取路径变量
}

@DeleteMapping("/users/{userId}/orders/{orderId}")
public void deleteOrder(
    @PathVariable String userId,
    @PathVariable String orderId) {
    // 多级路径变量
}

6.2 矩阵变量

// 需显式开启矩阵变量支持
@GetMapping("/products/{id}")
public Product getProduct(
    @PathVariable Long id,
    @MatrixVariable Map<String, String> matrixVars) {
    // 处理 /products/123;color=red;size=M 格式
}

七、参数校验机制

7.1 验证注解示例

@Data
public class UserDTO {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 4, max = 20)
    private String username;
    
    @Email
    private String email;
    
    @Pattern(regexp = "^(?=.*[A-Za-z])(?=.*\\d)[A-Za-z\\d]{8,}$")
    private String password;
    
    @Future
    private LocalDate birthday;
}

7.2 全局异常处理

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidationExceptions(
        MethodArgumentNotValidException ex) {
        // 处理验证错误
    }
}

八、自定义参数解析

8.1 类型转换器

@Configuration
public class WebConfig implements WebMvcConfigurer {
    
    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addConverter(new StringToLocalDateConverter());
    }
}

class StringToLocalDateConverter implements Converter<String, LocalDate> {
    @Override
    public LocalDate convert(String source) {
        return LocalDate.parse(source, DateTimeFormatter.ISO_DATE);
    }
}

8.2 自定义参数解析器

public class UserTokenArgumentResolver implements HandlerMethodArgumentResolver {

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.getParameterType().equals(UserToken.class);
    }

    @Override
    public Object resolveArgument(MethodParameter parameter, 
        ModelAndViewContainer mavContainer,
        NativeWebRequest webRequest, 
        WebDataBinderFactory binderFactory) {
        // 从请求中解析出UserToken对象
    }
}

九、参数处理最佳实践

9.1 分层参数对象

classDiagram
    class RequestDTO{
        <<interface>>
        +validate()
    }
    class UserCreateDTO{
        +username
        +password
        +email
        +validate()
    }
    class OrderQueryDTO{
        +page
        +size
        +sortBy
        +validate()
    }
    RequestDTO <|-- UserCreateDTO
    RequestDTO <|-- OrderQueryDTO

9.2 统一响应格式

@Data
@AllArgsConstructor
public class ApiResponse<T> {
    private long timestamp;
    private int code;
    private String message;
    private T data;
    
    public static <T> ApiResponse<T> success(T data) {
        return new ApiResponse<>(System.currentTimeMillis(), 200, "success", data);
    }
}

十、高级内容扩展

10.1 异步请求处理

@PostMapping("/async")
public CompletableFuture<ApiResponse<String>> asyncProcess(
    @RequestBody AsyncRequest request) {
    return CompletableFuture.supplyAsync(() -> {
        // 长时间处理逻辑
        return ApiResponse.success("处理完成");
    });
}

10.2 WebFlux参数处理

@RestController
@RequestMapping("/reactive")
public class ReactiveController {
    
    @PostMapping("/users")
    public Mono<User> createUser(@RequestBody Mono<UserDTO> userDto) {
        return userDto.flatMap(dto -> userService.create(dto));
    }
}

核心建议：