spring boot 默认将重复查询参数合并为逗号分隔字符串，但可通过 @requestparam multivaluemap 捕获原始多值结构，进而校验并拒绝含重复键的请求，实现严格的单值查询参数约束。
spring boot 默认将重复查询参数合并为逗号分隔字符串，但可通过 @requestparam multivaluemap 捕获原始多值结构，进而校验并拒绝含重复键的请求，实现严格的单值查询参数约束。
在构建符合严格规范的 RESTful API 时，有时需强制要求每个查询参数（query parameter）在整个 URL 中仅出现一次——例如，/my-api?foo=abc&foo=def 应被视为非法请求，并立即返回 HTTP 400 Bad Request，而非默认将其合并为 "abc,def"。遗憾的是，Spring Boot 不提供开箱即用的注解或配置项（如 @RequestParam(required = true, unique = true)）来声明式地启用该行为；但借助 MultiValueMap
✅ 正确做法：使用 MultiValueMap 获取原始参数结构
Spring MVC 允许将整个查询参数集以 MultiValueMap 形式注入控制器方法，它能真实反映客户端发送的参数键值对（包括重复键），而不会提前做合并处理：
@GetMapping("/my-api")
public ResponseEntity<string> handleRequest(
@RequestParam MultiValueMap<string string> params) {
// 检查是否存在任一参数键对应多个值（即被重复提交）
boolean hasDuplicate = params.values().stream()
.anyMatch(values -> values.size() > 1);
if (hasDuplicate) {
throw new ResponseStatusException(HttpStatus.BAD_REQUEST,
"Duplicate query parameters are not allowed");
}
// ✅ 安全继续：所有参数均为单值
String foo = params.getFirst("foo"); // 安全获取首个值（此时已确保唯一）
return ResponseEntity.ok("Processed: foo=" + foo);
}</string></string>
? 提示：params.getFirst("key") 是安全的替代方案，避免使用 @RequestParam String foo（它会触发自动合并，丢失重复信息）。
⚠️ 注意事项与最佳实践
- 不要混用：若方法中同时声明了 @RequestParam String foo 和 MultiValueMap，Spring 会优先处理前者并完成合并，导致 MultiValueMap 中的 foo 值可能已被“污染”或行为不可预测。务必只使用 MultiValueMap 统一接收所有查询参数。
- 全局统一校验（进阶）：若需在全站 API 层面强制执行该规则，可编写 HandlerInterceptor 或 Filter，在 DispatcherServlet 前解析原始 QueryString 并校验重复键（需手动解析 request.getQueryString()，注意编码与空格处理），但复杂度显著上升；对于多数场景，控制器内校验已足够清晰、可控且易于测试。
- 兼容性：该方案适用于 Spring Boot 2.x 和 3.x（基于 Spring Framework 5.3+），无需额外依赖。
通过上述方式，你既保持了代码的简洁性与可读性，又精准满足了业务对查询参数唯一性的强约束要求——无需侵入底层 HTTP 解析，也无需放弃 Spring 的声明式编程优势。
