Spring REST 安全校验枚举参数方法

本文介绍如何在 Spring Boot REST 端点中对传入的字符串型参数（如 "01"、"02"）进行严格枚举校验，确保仅接受预定义的合法值（如 Day.MONDAY → "01"），拒绝非法输入（如 "09"），并提供可复用的类型安全解决方案。

本文介绍如何在 Spring Boot REST 端点中对传入的字符串型参数（如 "01"、"02"）进行严格枚举校验，确保仅接受预定义的合法值（如 Day.MONDAY → "01"），拒绝非法输入（如 "09"），并提供可复用的类型安全解决方案。

在实际开发中，前端常以固定格式字符串（如两位数字编码 "01"）传递业务含义明确的参数，而后端需将其安全映射为 Java 枚举。但 Spring 默认的 @RequestParam 或 @PathVariable 绑定不支持直接按 value 字段反向解析枚举——若仅依赖 Day.valueOf("01") 会抛出 IllegalArgumentException（因枚举名是 MONDAY，非 "01"），且缺乏统一的校验入口。

✅ 正确做法：自定义 Converter + @Validated + @Pattern/自定义注解，实现类型安全、可复用、可扩展的校验链。

✅ 推荐方案：基于 Converter 的声明式校验

首先修正枚举构造函数名（原代码中误写为 Event，应为 Day）并添加静态查找方法：

public enum Day {
    MONDAY("01"),
    TUESDAY("02"),
    WEDNESDAY("03"),
    THURSDAY("04"),
    FRIDAY("05"),
    SATURDAY("06"),
    SUNDAY("07");

    private final String value;

    Day(String value) { // 修正构造函数名
        this.value = value;
    }

    public String getValue() {
        return value;
    }

    // 安全查找：返回 Optional 避免 NPE
    public static Optional fromValue(String value) {
        for (Day day : Day.values()) {
            if (day.value.equals(value)) {
                return Optional.of(day);
            }
        }
        return Optional.empty();
    }
}

接着，注册一个 Spring Converter，将字符串自动转换为 Day，并在转换失败时抛出带语义的异常：

@Component
public class StringToDayConverter implements Converter {
    @Override
    public Day convert(String source) {
        if (source == null || source.trim().isEmpty()) {
            throw new IllegalArgumentException("Day parameter cannot be null or empty");
        }
        return Day.fromValue(source.trim())
                .orElseThrow(() -> new IllegalArgumentException(
                        "Invalid Day value: '" + source + "'. Allowed: 01-07"));
    }
}

在 WebMvcConfigurer 中注册该转换器（Spring Boot 2.6+ 可省略，自动扫描 @Component）：

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

最后，在 Controller 中直接使用，Spring 将自动完成转换与校验：

@RestController
@RequestMapping("/api")
public class DayController {

    @GetMapping("/schedule")
    public ResponseEntity getSchedule(@RequestParam Day day) {
        return ResponseEntity.ok("Selected day: " + day.name() + " (" + day.getValue() + ")");
    }
}

✅ 效果验证：

• ✅ /api/schedule?day=01 → 返回 MONDAY (01)
• ✅ /api/schedule?day=07 → 返回 SUNDAY (07)
• ❌ /api/schedule?day=09 → 抛出 IllegalArgumentException，HTTP 400 响应体含清晰错误信息

⚠️ 注意事项与最佳实践

• 不要依赖 Integer.parseInt() 后匹配序号：原始答案建议“转为数字再校验 1–7”，虽可行但破坏了枚举的语义封装性，且无法处理非连续编号（如 "01", "03", "10"）；
• 避免在 Controller 内手动 try-catch 解析：违背关注点分离，重复代码且难以全局统一错误响应格式；
• 生产环境建议配合全局异常处理器，将 IllegalArgumentException 映射为标准 JSON 错误响应（如 {"error": "Invalid Day value: '09'"}）；
• 若需支持多语言或更复杂校验逻辑（如权限级校验），可升级为 @Constraint 自定义注解 + ConstraintValidator。

通过以上设计，你获得了一个零侵入、可测试、易维护、符合 Spring 生态规范的枚举参数校验方案——既保障 API 健壮性，又提升团队协作效率。