跳至主要內容

Spring Controller 参数接收

JustQ2025/11/30大约 5 分钟Java-learningJavaWebjavaspringbootcontrollerparameterannotationtutorialintermediate

Controller参数

1. 常用参数接收注解概览

注解作用位置主要用途数据来源
@PathVariable方法参数获取 URL 路径中的参数URL 路径
@RequestParam方法参数获取 URL 查询参数URL ? 后面
@RequestBody方法参数获取请求体（如 JSON）请求体
@RequestHeader方法参数获取请求头信息HTTP Header
@CookieValue方法参数获取 Cookie 值Cookie
@ModelAttribute方法参数绑定表单数据请求参数/体

2. 详细讲解各个注解

2.1 @PathVariable - 路径变量

从 URL 路径中提取变量值。

示例：

@RestController
@RequestMapping("/api/users")
public class UserController {

    // GET /api/users/123
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        // id = 123
        User user = userService.findById(id);
        return ResponseEntity.ok(user);
    }

    // GET /api/users/123/orders/456
    @GetMapping("/{userId}/orders/{orderId}")
    public ResponseEntity<Order> getOrder(
            @PathVariable Long userId,
            @PathVariable Long orderId) {
        // userId = 123, orderId = 456
        Order order = orderService.findByUserAndOrderId(userId, orderId);
        return ResponseEntity.ok(order);
    }

    // 路径变量名与方法参数名不同时，需要指定
    @GetMapping("/{userId}")
    public ResponseEntity<User> getUser(
            @PathVariable("userId") Long id) {
        // 使用 @PathVariable("userId") 明确指定
        User user = userService.findById(id);
        return ResponseEntity.ok(user);
    }
}

2.2 @RequestParam - 请求参数

从 URL 查询字符串中获取参数。

示例：

@RestController
@RequestMapping("/api/users")
public class UserController {
	
	//解析同名
	//GET /api/users?ids=1,2,3
	@GetMapping
	public Result getUsers(@RequestParam List<Long> ids){
		
	}

    // GET /api/users?page=1&size=20&name=张三
    @GetMapping
    public ResponseEntity<Page<User>> getUsers(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "10") int size,
            @RequestParam(required = false) String name) {
        // page = 1, size = 20, name = "张三"
        Page<User> users = userService.findUsers(page, size, name);
        return ResponseEntity.ok(users);
    }

    // 获取所有查询参数作为 Map
    @GetMapping("/search")
    public ResponseEntity<List<User>> searchUsers(
            @RequestParam Map<String, String> allParams) {
        // allParams 包含所有查询参数
        List<User> users = userService.searchByParams(allParams);
        return ResponseEntity.ok(users);
    }

    // 获取同名的多个参数值
    @GetMapping("/filter")
    public ResponseEntity<List<User>> filterUsers(
            @RequestParam List<String> tags) {
        // GET /api/users/filter?tags=java&tags=spring&tags=boot
        // tags = ["java", "spring", "boot"]
        List<User> users = userService.findByTags(tags);
        return ResponseEntity.ok(users);
    }
}

@RequestParam 常用属性：

  • required：是否必须，默认 true
  • defaultValue：默认值
  • name/value：参数名称

2.3 @RequestBody - 请求体

将请求体（通常是 JSON）绑定到 Java 对象。

示例：

@RestController
@RequestMapping("/api/users")
public class UserController {

    // POST /api/users
    // Content-Type: application/json
    // Body: {"name":"张三","age":25,"email":"zhangsan@example.com"}
    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        // user 对象已自动从 JSON 反序列化
        User savedUser = userService.save(user);
        return ResponseEntity.status(HttpStatus.CREATED).body(savedUser);
    }

    // 使用 DTO (Data Transfer Object) 接收参数
    @PostMapping("/register")
    public ResponseEntity<User> registerUser(@RequestBody UserRegisterDTO registerDTO) {
        // 使用专门的 DTO 接收注册信息，避免暴露实体类
        User user = userService.register(registerDTO);
        return ResponseEntity.status(HttpStatus.CREATED).body(user);
    }

    // 接收列表
    @PostMapping("/batch")
    public ResponseEntity<List<User>> createUsers(@RequestBody List<User> users) {
        // Body: [{"name":"张三"},{"name":"李四"}]
        List<User> savedUsers = userService.batchSave(users);
        return ResponseEntity.status(HttpStatus.CREATED).body(savedUsers);
    }

    // 接收 Map
    @PostMapping("/map")
    public ResponseEntity<Map<String, Object>> handleMap(@RequestBody Map<String, Object> data) {
        // 可以接收任意 JSON 对象
        return ResponseEntity.ok(data);
    }
}

DTO 示例：

// 专门的请求 DTO
public class UserRegisterDTO {
    @NotBlank(message = "用户名不能为空")
    private String username;
    
    @Email(message = "邮箱格式不正确")
    private String email;
    
    @Size(min = 6, message = "密码长度至少6位")
    private String password;
    
    // getter, setter 省略
}

2.4 @RequestHeader - 请求头

获取 HTTP 请求头信息。

示例：

@RestController
public class AuthController {

    @GetMapping("/profile")
    public ResponseEntity<User> getProfile(
            @RequestHeader("Authorization") String authHeader,
            @RequestHeader("User-Agent") String userAgent) {
        // 处理认证头信息
        String token = authHeader.replace("Bearer ", "");
        User user = authService.validateToken(token);
        return ResponseEntity.ok(user);
    }

    // 获取所有请求头
    @GetMapping("/headers")
    public ResponseEntity<Map<String, String>> getAllHeaders(
            @RequestHeader Map<String, String> headers) {
        // headers 包含所有请求头信息
        return ResponseEntity.ok(headers);
    }

    // 设置默认值
    @GetMapping("/lang")
    public ResponseEntity<String> getContent(
            @RequestHeader(value = "Accept-Language", defaultValue = "zh-CN") String language) {
        // 根据语言返回不同内容
        return ResponseEntity.ok("Current language: " + language);
    }
}

2.5 @CookieValue - Cookie 值

获取 Cookie 信息。

示例：

@RestController
public class SessionController {

    @GetMapping("/session")
    public ResponseEntity<Session> getSession(
            @CookieValue("JSESSIONID") String sessionId) {
        Session session = sessionService.getSession(sessionId);
        return ResponseEntity.ok(session);
    }

    // 非必须的 Cookie
    @GetMapping("/preferences")
    public ResponseEntity<Preferences> getPreferences(
            @CookieValue(value = "user-prefs", required = false) String preferences) {
        if (preferences != null) {
            // 解析偏好设置
            return ResponseEntity.ok(parsePreferences(preferences));
        }
        return ResponseEntity.ok(new Preferences());
    }
}

2.6 @ModelAttribute - 模型属性

主要用于表单数据处理。

示例：

@Controller
@RequestMapping("/web/users")
public class WebUserController {

    // 处理表单提交
    @PostMapping("/create")
    public String createUser(@ModelAttribute User user) {
        userService.save(user);
        return "redirect:/users";
    }

    // 绑定前缀
    @PostMapping("/search")
    public String searchUsers(@ModelAttribute("searchForm") SearchForm form) {
        // 处理搜索表单
        return "search-results";
    }
}

3. 综合使用示例

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    // 综合使用多种注解
    @PostMapping("/{orderId}/items")
    public ResponseEntity<Order> addOrderItem(
            @PathVariable Long orderId,                    // 路径参数
            @RequestBody OrderItemDTO itemDTO,            // 请求体
            @RequestHeader("X-User-Id") Long userId,      // 自定义请求头
            @RequestParam(defaultValue = "false") boolean merge, // 查询参数
            HttpServletRequest request) {                 // 原生请求对象
        
        // 验证用户权限
        if (!orderService.isOrderOwner(orderId, userId)) {
            return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
        }
        
        // 处理订单项
        Order order = orderService.addItem(orderId, itemDTO, merge);
        
        return ResponseEntity.ok(order);
    }
}

4. 验证和错误处理

结合 Validation API 进行参数验证：

@RestController
@RequestMapping("/api/users")
public class UserController {

    @PostMapping
    public ResponseEntity<?> createUser(@Valid @RequestBody UserCreateDTO userDTO, 
                                      BindingResult result) {
        // 如果验证失败
        if (result.hasErrors()) {
            Map<String, String> errors = new HashMap<>();
            for (FieldError error : result.getFieldErrors()) {
                errors.put(error.getField(), error.getDefaultMessage());
            }
            return ResponseEntity.badRequest().body(errors);
        }
        
        User user = userService.create(userDTO);
        return ResponseEntity.status(HttpStatus.CREATED).body(user);
    }
}

// DTO 类
public class UserCreateDTO {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度3-20位")
    private String username;

    @Email(message = "邮箱格式不正确")
    private String email;

    @Min(value = 18, message = "年龄必须大于18岁")
    private Integer age;

    // getter, setter 省略
}

5. 最佳实践

  1. 使用 DTO：不要直接用 Entity 类接收请求参数
  2. 合理使用默认值：为可选参数设置合理的默认值
  3. 参数验证：始终验证输入参数
  4. 保持一致性：在整个项目中保持参数命名和风格一致
  5. 文档化：使用 Swagger/OpenAPI 文档化 API 参数

这些注解是 Spring Boot 开发的基础，熟练掌握它们对于构建健壮的 RESTful API 至关重要。

默认页脚
Copyright © 2025 JustQ