SpringBoot3集成OAS3时多值查询参数id的正则校验异常问题

针对你遇到的三个校验问题，核心原因是未正确配置匹配逗号分隔多值的正则规则，且原规则缺少字符串边界校验，导致部分非法值绕过校验。以下是具体解决方案：

问题根源分析 #

当设置explode=false时，OpenAPI会将多个id合并为单个字符串参数传递。如果仅使用单个id的正则[a-zA-Z0-9]{5,15}，会出现以下问题：

• 缺少^（开头）和$（结尾）边界，导致只要字符串包含合法子串就通过校验（如@12345中的12345匹配前5位）
• 未定义逗号分隔的结构规则，无法识别多个id的分隔逻辑，导致带非法字符的整串被当作单个值处理

解决方案 #

1. 修正OpenAPI Schema的正则规则 #

使用能匹配整个逗号分隔字符串的正则，确保每个分段都是合法id，且无多余字符：

^[a-zA-Z0-9]{5,15}(,[a-zA-Z0-9]{5,15})*$

规则解释：

• ^：匹配字符串开头，确保无前置非法字符
• [a-zA-Z0-9]{5,15}：匹配第一个合法id（5-15位字母/数字）
• (,[a-zA-Z0-9]{5,15})*：匹配零个或多个以逗号分隔的合法id
• $：匹配字符串结尾，确保无后置非法字符

2. 后端代码同步校验 #

为了保证后端与Swagger校验一致，在控制器层添加双重校验：

方式一：接收字符串并校验整串

@GetMapping("/your-api-path")
public ResponseEntity<?> fetchData(
    @RequestParam("id")
    @Pattern(
        regexp = "^[a-zA-Z0-9]{5,15}(,[a-zA-Z0-9]{5,15})*$",
        message = "每个id必须是5-15位字母/数字，多值用逗号分隔"
    )
    String idsStr
) {
    // 拆分字符串为id列表，后续业务处理
    List<String> ids = Arrays.asList(idsStr.split(","));
    return ResponseEntity.ok(ids);
}

方式二：直接接收列表并校验每个元素

如果希望Spring自动拆分逗号分隔的字符串为列表，可结合@Valid和元素级别的@Pattern：

@GetMapping("/your-api-path")
public ResponseEntity<?> fetchData(
    @RequestParam("id")
    @Valid @Size(min = 1, message = "至少传入一个id")
    List<@Pattern(
        regexp = "[a-zA-Z0-9]{5,15}",
        message = "id必须是5-15位字母/数字"
    ) String> ids
) {
    return ResponseEntity.ok(ids);
}

这种方式下，需确保OpenAPI配置中explode=false，同时schema的pattern仍使用整串匹配规则，保证Swagger UI的校验正常。

3. OpenAPI注解配置示例 #

如果使用SpringDoc（SpringBoot3推荐的OAS3实现），控制器上的参数配置如下：

@Operation(summary = "根据多个id查询数据")
@Parameter(
    name = "id",
    description = "多个id用逗号分隔，每个id为5-15位字母或数字",
    required = true,
    explode = false,
    schema = @Schema(
        type = "string",
        pattern = "^[a-zA-Z0-9]{5,15}(,[a-zA-Z0-9]{5,15})*$"
    )
)

验证效果 #

修正后，三个问题会被彻底解决：

• 非法开头的字符串（如@12345）会被^拦截，无法通过校验
• 带非法字符的逗号分隔串（如2RXB859H4IWSF]},##2RXB859H4IWSF）不符合整串规则，直接被拒绝
• 单个非法值（如2RXB859H4IWSF]}）因不符合$结尾规则，无法通过校验

内容的提问来源于stack exchange，提问作者Abdullah Imran