Swagger生成Spring Controller接收POST请求体参数为NULL问题排查

看起来你遇到的核心问题是Swagger API定义的参数配置不一致，导致Swagger UI和生成的TypeScript客户端采用了完全不同的参数传递方式，进而让Spring的@RequestBody无法正确解析。下面一步步帮你排查和解决：

1. 先排查Swagger API定义的问题 #

这是最可能的根源——你的Swagger规范（yaml/json）里，这个POST接口的参数定义大概率混乱了：要么把本该放在请求体的参数错误标记为in: query，要么同时混合了query参数和requestBody的定义。

正确的POST请求体定义应该是这样的（以OpenAPI 3.0为例）：

paths:
  /your-api-endpoint:
    post:
      summary: 你的接口描述
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/YourRequestModel'
      responses:
        '200':
          description: 请求成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YourResponseModel'

要确保所有需要放在请求体的参数都通过requestBody定义，而不是塞进parameters数组里标记为in: query。Swagger UI会严格按照定义生成请求，而有些代码生成器可能对不规范的定义做出错误解读，导致客户端发送请求体而不是查询参数。

2. 验证TypeScript客户端的请求格式 #

生成的TS客户端可能存在两个问题：

• 请求头未设置Content-Type: application/json：Spring只有在收到这个请求头时，才会用Jackson去解析JSON请求体，否则会忽略请求体，导致@RequestBody为null。
• 请求体序列化错误：比如把对象直接作为FormData发送，而不是序列化为JSON字符串。

你可以通过浏览器开发者工具（Network面板）抓包，查看TS客户端发送的请求：

• 确认Request Headers里有Content-Type: application/json
• 确认Request Body是标准的JSON格式，而不是键值对形式的查询字符串

如果生成的客户端代码有问题，可以手动调整请求逻辑，比如用axios的示例：

import axios from 'axios';
import { YourRequestModel } from './models';

export async function sendPostRequest(requestData: YourRequestModel) {
  try {
    const response = await axios.post('/your-api-endpoint', requestData, {
      headers: {
        'Content-Type': 'application/json',
      },
    });
    return response.data;
  } catch (error) {
    console.error('请求失败:', error);
    throw error;
  }
}

3. 检查Spring服务器的配置和DTO类 #

即使请求格式正确，Spring也可能因为配置或DTO类的问题无法解析：

• 确保Jackson依赖存在：如果是Spring Boot项目，默认已经包含spring-boot-starter-web，里面自带Jackson；如果是纯Spring项目，需要手动引入Jackson的依赖包。
• DTO类要符合要求：
  • 必须有无参构造函数（Lombok的@Data会自动生成，手动写的话要加上）
  • 字段要有对应的getter/setter（同样@Data可以搞定）
  • 如果JSON字段名和DTO字段名不一致，要用@JsonProperty指定映射，比如：

    @Data
    public class YourRequestDto {
        @JsonProperty("user_name")
        private String userName;
        private Integer age;
    }
    

• 控制器方法的注解要正确：确保用的是@PostMapping，参数上的@RequestBody没有写错，并且参数类型是对应的DTO类。

4. 用Postman做一致性测试 #

为了定位问题到底在客户端还是服务器，可以用Postman模拟请求：

1. 发送POST请求到你的接口地址
2. 设置请求头Content-Type: application/json
3. 在Body里选择raw -> JSON，填入和TS客户端相同的JSON参数
4. 发送请求，看Spring是否能正确接收参数

如果Postman能正常接收，说明问题出在TS客户端的生成或配置上；如果Postman也返回null，那问题就出在Swagger定义或Spring端的配置上。

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