springboot controller 参数非必填

在 Spring Boot 的 Controller 中，设置参数为非必填是常见需求。以下是几种常见参数类型及其非必填设置方式，包含代码示例和注意事项：

---

1. @RequestParam 参数非必填

方法一：设置 required = false

@GetMapping("/users")
public ResponseEntity<?> getUsers(
    @RequestParam(required = false) String name,
    @RequestParam(required = false) Integer age
) {
    // name 和 age 可为 null
}

方法二：设置默认值（推荐）

@GetMapping("/users")
public ResponseEntity<?> getUsers(
    @RequestParam(defaultValue = "0") Integer page,
    @RequestParam(defaultValue = "10") Integer size,
    @RequestParam(required = false) String keyword
) {
    // page 默认 0，size 默认 10，keyword 可为 null
}

方法三：使用 Optional 包装（Spring 4.2+）

@GetMapping("/users")
public ResponseEntity<?> getUsers(
    @RequestParam Optional<String> name,
    @RequestParam Optional<Integer> age
) {
    String nameValue = name.orElse("default");
}

---

2. @PathVariable 参数（通常必填）

@PathVariable 默认是必填的，但可通过以下方式实现"可选"效果：

方法一：定义多个映射路径

@GetMapping("/users")
public ResponseEntity<?> getAllUsers() {
    // 无参数
}

@GetMapping("/users/{id}")
public ResponseEntity<?> getUserById(@PathVariable Long id) {
    // 有 id 参数
}

方法二：使用 @RequestParam 替代

@GetMapping("/users")
public ResponseEntity<?> getUsers(@RequestParam(required = false) Long id) {
    // id 可选
}

---

3. @RequestBody 对象中的字段非必填

在 DTO 中，字段默认就是可选的，只需确保不使用 @NotNull 等校验注解：

public class UserDTO {
    private String name;        // 非必填
    private Integer age;        // 非必填

    // getter/setter
}

@PostMapping("/users")
public ResponseEntity<?> createUser(@RequestBody UserDTO userDTO) {
    // name 和 age 可为 null
}

结合校验注解（如需要部分必填）

public class UserDTO {
    @NotNull(message = "用户名不能为空")
    private String name;

    private Integer age;  // 非必填
}

---

4. 综合示例：查询接口支持多可选参数

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

    @GetMapping
    public ResponseEntity<?> listUsers(
        @RequestParam(required = false) String name,
        @RequestParam(required = false) Integer age,
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "10") int size,
        @RequestParam(required = false) String sortBy
    ) {
        // 构建查询条件
    }
}

---

5. 参数处理最佳实践

空值处理工具类

public class ParamUtils {
    public static String getStringParam(Optional<String> param, String defaultValue) {
        return param.filter(s -> !s.isBlank()).orElse(defaultValue);
    }

    public static Integer getIntParam(Optional<Integer> param, Integer defaultValue) {
        return param.orElse(defaultValue);
    }
}

统一参数封装（推荐用于复杂查询）

public class QueryParam {
    private String name;
    private Integer age;
    private Integer page = 0;
    private Integer size = 10;

    // getter/setter
}

@PostMapping("/search")
public ResponseEntity<?> search(@RequestBody QueryParam param) {
    // 所有字段均为非必填
}

---

6. 注意事项

场景	建议
基本类型（int、long）	使用包装类（Integer、Long）或设置默认值，避免空指针
字符串参数	注意空字符串 "" 与 null 的区别
参数校验	使用 @Valid + JSR 校验注解（如 @NotNull）
文档说明	使用 Swagger/OpenAPI 标注参数是否必填

Swagger 示例

@ApiOperation("查询用户")
public ResponseEntity<?> listUsers(
    @ApiParam(required = false) @RequestParam(required = false) String name,
    @ApiParam(required = true, defaultValue = "0") @RequestParam int page
) {
    // ...
}

---

7. 常见问题解决

问题：基本类型参数传空报错

// ❌ 错误示例
@GetMapping("/test")
public String test(@RequestParam int age) { }  // age 不能为 null

// ✅ 正确示例
@GetMapping("/test")
public String test(@RequestParam(required = false) Integer age) { }

问题：空字符串处理

@RequestParam(required = false) String name

// 建议处理
if (name != null && !name.trim().isEmpty()) {
    // 有效参数
}

---

通过以上方式，你可以灵活地设置 Spring Boot Controller 中的参数为非必填，提升接口的健壮性与可用性。根据具体业务场景选择合适的方式，并注意空值处理与参数校验。