ASP.NET Core POST请求JSON映射异常排查求助

问题根源 #

ASP.NET Core 默认不会从单个 JSON 请求体中同时绑定多个独立的方法参数（复杂类型+简单类型）。你当前的写法会导致模型绑定逻辑混乱，错误地将 JSON 中的顶级属性映射到第一个复杂类型参数的字段中，同时无法正确解析其他属性。

方案一：创建统一的请求 DTO（推荐） #

这是最规范且不易出错的方式，把所有需要从 JSON 体接收的参数封装到一个类中：

1. 定义请求 DTO 类

public class CreateProjectUserRequest
{
    [JsonPropertyName("projectUser")]
    public HikariUser ProjectUser { get; set; }

    [JsonPropertyName("userName")]
    public string UserName { get; set; }
}

2. 修改 API 端点签名
   将原方法的两个参数替换为这个 DTO，显式添加 [FromBody] 特性让框架明确从请求体绑定数据：

[HttpPost("CreateProjectUser")]
public async Task<ActionResult> CreateProjectUserAsync([FromBody] CreateProjectUserRequest request)
{
    // 直接使用 DTO 中的属性进行业务处理
    var projectUser = request.ProjectUser;
    var userName = request.UserName;
    // ... 后续业务逻辑代码
}

3. 调整 JSON 请求体属性大小写
   确保 JSON 中 projectUser 的子属性和 HikariUser 类里 [JsonPropertyName] 指定的名称完全匹配（System.Text.Json 默认大小写敏感）：

{
    "projectUser": {
        "username": "exampleProjectUser",
        "email": "exampleProjectUser1@example.com",
        "password": "Abc!123",
        "role": "Contributor"
    },
    "userName": "AM" 
}

方案二：通过查询字符串传递简单类型参数 #

如果不想创建 DTO，可以把 userName 放到 URL 查询字符串中，JSON 体仅传递 projectUser：

1. 修改 API 端点签名
   给 projectUser 添加 [FromBody] 指定从请求体绑定，userName 用 [FromQuery] 指定从查询字符串获取：

[HttpPost("CreateProjectUser")]
public async Task<ActionResult> CreateProjectUserAsync([FromBody] HikariUser projectUser, [FromQuery] string userName)
{
    // ... 业务逻辑代码
}

2. 调整请求内容

• JSON 请求体仅保留 projectUser 的属性：

{
    "username": "exampleProjectUser",
    "email": "exampleProjectUser1@example.com",
    "password": "Abc!123",
    "role": "Contributor"
}

• 请求 URL 改为：POST /CreateProjectUser?userName=AM

关键注意事项 #

• [JsonPropertyName] 必须和 JSON 属性名称完全匹配（包括大小写），否则无法正确映射。
• 每个 POST 方法只能有一个 [FromBody] 参数，因为请求体只能被读取一次。

内容的提问来源于stack exchange，提问作者Ahune ajé o ahe