Spring Boot POST 请求返回空数组 [] 是什么原因导致的，又该如何解决？

在 Spring Boot 项目里，写了一个接收 POST 请求的接口，期望返回查询到的用户列表，结果前端拿到的却是一个空数组 []。这种现象背后通常有多种技术诱因，包括参数绑定失败、序列化配置不当以及注解使用错误等。只有逐一排查这些环节，才能准确定位并修复问题。

一、常见导致空数组的原因

1. 缺少 @RequestBody 注解

当控制器方法使用一个自定义对象来接收 POST 的 JSON 参数时，如果没有添加 @RequestBody，Spring 不会将请求体中的 JSON 反序列化为该对象，而是尝试从请求参数或表单字段中绑定。结果对象里的字段全部为 null，后续用这些 null 值去查数据库，自然返回空结果。

例如下面这段有问题的代码，方法参数前没有注解，Spring 将其视为普通表单绑定，JSON 内容被直接忽略：

@RestController
@RequestMapping("/user")
public class UserController {

    @PostMapping("/list")
    public List<User> list(UserQuery query) {
        // query.getName() 为 null，查询条件失效
        return userService.find(query);
    }
}

这种写法在 GET 请求中或许能工作，但 POST 提交 JSON 时就会出问题。很多初学者误以为 @RestController 已经帮我们处理了所有入参，实际上方法级别仍需要明确告诉框架请求体如何映射。

2. 实体类字段与 JSON 属性名不一致

Jackson 是 Spring Boot 默认的 JSON 处理库。如果前端传递的字段是 user_name，而后端实体类属性是 userName 且没有配置命名策略或 @JsonProperty，反序列化时该字段就会被忽略，对象只得到部分数据或空数据。

假设前端发送如下 JSON：

{
  "user_name": "tom",
  "age": 20
}

后端实体若未做映射，userName 值为 null。当业务代码用 userName 做等值查询时，条件不匹配任何记录，返回空数组。可以通过在字段上加 @JsonProperty("user_name") 或在配置文件中开启驼峰转下划线来解决。

3. 返回结构被视图解析干扰

如果控制器类标注的是 @Controller 而不是 @RestController，且方法没有加 @ResponseBody，Spring 会认为你要返回一个视图名称。此时若返回了一个 List，框架尝试把它当作逻辑视图名，最终响应体可能为空或抛出异常，前端解析后表现为空数组或解析失败。

错误示例如下：

@Controller
public class OrderController {

    @PostMapping("/orders")
    public List<Order> orders() {
        return orderService.all(); // 没有 @ResponseBody
    }
}

这种配置在前后端分离项目中是致命的，因为前端只认 JSON，而后端却在找模板文件。

二、对应的解决方案

1. 正确添加 @RequestBody

将接收 JSON 对象的参数用 @RequestBody 标注，确保请求体被正确反序列化。修改后的代码如下：

@RestController
@RequestMapping("/user")
public class UserController {

    @PostMapping("/list")
    public List<User> list(@RequestBody UserQuery query) {
        // query 中的属性已被正确赋值
        return userService.find(query);
    }
}

这样 Spring 会使用 HttpMessageConverter 读取输入流，并借助 Jackson 完成对象映射。同时建议在入参对象上增加基础校验，比如 @NotBlank，避免空条件查询。

2. 统一 JSON 命名与序列化配置

如果团队约定前端使用下划线风格，可以在 application.properties 中配置：

spring.jackson.property-naming-strategy=SNAKE_CASE

或者在实体类字段上精确控制：

public class UserQuery {
    @JsonProperty("user_name")
    private String userName;
    private Integer age;
    // getter 和 setter 省略
}

统一规则后，反序列化不再丢字段，查询条件才能真实反映前端意图。另外注意日期格式、布尔值等类型也应明确，防止隐性转换错误。

3. 使用 @RestController 或 @ResponseBody

对于纯接口服务，直接将类声明为 @RestController，它已经组合了 @Controller 和 @ResponseBody。若必须沿用 @Controller，请给每个返回数据的方法加上 @ResponseBody。

@RestController
public class OrderController {

    @PostMapping("/orders")
    public List<Order> orders() {
        return orderService.all();
    }
}

这样响应会直接写入 HTTP body，并以 JSON 形式输出，前端拿到的就是标准的数组结构，而不是被视图解析器扭曲的内容。

三、排查与调试建议

1. 开启请求日志

在 application.properties 中打开 Spring Web 的调试日志，观察实际接收到的请求体和绑定的参数对象：

logging.level.org.springframework.web=DEBUG

通过日志可以确认 JSON 是否进入方法，以及反序列化后的对象是否包含预期数值。如果日志里对象字段全空，就能反推是注解或命名问题。

2. 使用 Postman 或 curl 自测

不要只依赖前端页面，用工具直接发 POST 请求，指定 Content-Type 为 application/json。对比不同入参下的返回，能快速区分是后端逻辑还是前端传参故障。

curl -X POST http://127.0.0.1:8080/user/list 
  -H "Content-Type: application/json" 
  -d '{"userName":"tom","age":20}'

如果自测接口正常而前端异常，重点检查前端 axios 或 fetch 是否真正以 JSON 格式发送，以及是否有拦截器篡改了数据。

四、总结

核心要点回顾

Spring Boot POST 返回空数组通常不是数据库没数据，而是参数没接住、字段没映射或响应没序列化。牢记给 JSON 入参加 @RequestBody，保持前后端字段命名一致，并用 @RestController 保证输出为 JSON。

把这些基础配置固化到项目脚手架中，新接口就能避免重复踩坑。当异常出现时，从请求体、实体映射和响应类型三个维度切入，基本可以在几分钟内定位根源。

Spring_BootPOST请求空数组修改时间：2026-08-01 14:36:39