本文详解 spring boot 控制器接收 json 数组与字符串混合参数的正确方式，重点解决因请求体结构不匹配导致的 415 unsupported media type 错误。
本文详解 spring boot 控制器接收 json 数组与字符串混合参数的正确方式，重点解决因请求体结构不匹配导致的 415 unsupported media type 错误。
在使用 Spring Boot 开发 REST API 时，若控制器方法直接声明多个参数（如 @RequestBody List
✅ 正确做法：封装为统一 DTO 对象
Spring 的 @RequestBody 只能绑定整个 JSON 对象到一个 Java 对象（即 DTO），不能拆分映射到多个方法参数。因此，需定义一个承载所有字段的请求体类：
public class SendCustomMessageRequest {
private List<Integer> accounts;
private String message;
// 必须提供无参构造器（Jackson 反序列化所需）
public SendCustomMessageRequest() {}
// Getter 和 Setter（IDE 可自动生成）
public List<Integer> getAccounts() {
return accounts;
}
public void setAccounts(List<Integer> accounts) {
this.accounts = accounts;
}
public String getMessage() {
return message;
}
public void setMessage(String message) {
this.message = message;
}
}然后更新控制器方法，仅接收一个 @RequestBody 参数：
@PostMapping("/sendCustomMessage")
public ResponseEntity<Void> sendCustomMessage(@RequestBody SendCustomMessageRequest request) {
List<Integer> accounts = request.getAccounts();
String message = request.getMessage();
// 调用业务逻辑（示例）
// telegramService.sendGroupMessageByAccountIdList(accounts, message);
return ResponseEntity.ok().build();
}? Postman 配置要点
- Method: POST
- URL: http://localhost:8080/api/telegram/sendCustomMessage（按实际调整）
- Headers → 添加：Content-Type: application/json
- Body → 选择 raw → JSON，输入标准 JSON 对象：
{
"accounts": [1, 2, 3],
"message": "Custom Message"
}⚠️ 注意：不要使用 x-www-form-urlencoded 或 form-data，它们无法解析嵌套数组；也不可省略 Content-Type 头，否则 Spring 默认不尝试 JSON 解析。
❌ 常见错误排查
| 错误现象 | 原因 | 修复方案 |
|---|---|---|
| 415 Unsupported Media Type | @RequestBody 与普通参数混用，或缺少 Content-Type: application/json | 改用单一 DTO + 显式设置 Header |
| 400 Bad Request / 字段为 null | DTO 缺少 getter/setter、无参构造器，或 JSON 字段名与 Java 属性名不匹配（如大小写） | 使用 @JsonProperty("accounts") 显式指定映射，或启用 spring.jackson.property-naming-strategy=SNAKE_CASE |
| HttpMessageNotReadableException | JSON 格式非法（如尾逗号、单引号、中文引号） | 在 Postman 中使用 JSON 格式校验工具，确保语法严格合规 |
✅ 进阶建议（可选）
- 若需支持多种请求结构，可结合 @JsonUnwrapped 或 @JsonAlias 增强兼容性；
- 生产环境建议添加 @Valid + @NotNull / @Size 等校验注解，并配合全局异常处理器统一返回格式；
- 使用 Lombok 可大幅简化 DTO 代码（@Data, @NoArgsConstructor）。
遵循以上结构，即可稳定、清晰、可维护地接收含整数列表的 JSON 请求体——这是 Spring Boot REST API 开发中的基础但关键的最佳实践。
