.NET Core 7中如何通过FromForm传递含嵌套对象的类至API

问题核心是.NET Core表单绑定对嵌套对象的参数命名有特定要求，没遵循的话会导致整个模型绑定失败，所有属性都为空。按以下步骤调整就能解决：

1. 确保嵌套类属性可被绑定 #

首先检查SecondLevel类的所有属性都有公共的getter和setter，模型绑定需要可读写的属性才能正常赋值：

public class SecondLevel
{
    public int Id { get; set; }
    public string LevelName { get; set; }
    // 其他属性都要保持public且有get/set
}

2. 用点标记法传递嵌套对象的属性 #

不管用Swagger、AJAX还是curl，传递嵌套对象的属性时，必须用Level.属性名的格式命名参数，这样绑定器才能识别并映射到嵌套对象：

curl示例 #

curl -X POST "https://your-api-domain/api/level" \
-F "HomePlanId=HP-202405" \
-F "NewImageFiles=@front.jpg" \
-F "NewImageFiles=@back.jpg" \
-F "Level.Id=5" \
-F "Level.LevelName=SubLevelOne"

AJAX示例 #

const formData = new FormData();
// 添加基础属性
formData.append('HomePlanId', 'HP-202405');
// 添加文件
formData.append('NewImageFiles', document.getElementById('fileInput').files[0]);
formData.append('NewImageFiles', document.getElementById('fileInput').files[1]);
// 添加嵌套对象属性
formData.append('Level.Id', 5);
formData.append('Level.LevelName', 'SubLevelOne');

fetch('/api/level', {
    method: 'POST',
    body: formData
})
.then(res => res.json())
.then(data => console.log(data));

Swagger操作 #

在Swagger页面填写参数时，直接把嵌套属性写成Level.Id、Level.LevelName的格式即可，Swagger会自动识别并生成正确的表单请求。

3. 验证控制器接口定义 #

确保控制器的POST方法正确标记了[FromForm]，参数类型为LevelData：

[ApiController]
[Route("api/level")]
public class LevelController : ControllerBase
{
    [HttpPost]
    public IActionResult CreateLevel([FromForm] LevelData model)
    {
        // 这里就能正常获取到所有属性值了
        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }
        // 业务逻辑处理
        return Ok(model);
    }
}

原理说明 #

.NET Core的表单模型绑定器处理复杂嵌套对象时，依赖点分隔的命名约定来关联父模型和嵌套对象的属性。如果没有用这种方式传递参数，绑定器无法解析嵌套对象的结构，会直接判定模型绑定失败，导致所有属性都为空值。

内容的提问来源于stack exchange，提问作者Pablo Andres Barrantes