.NET 7 Minimal API为何默认从QueryString绑定而非请求体？

问题根源 #

Minimal API的参数绑定遵循默认规则：

• 简单类型（如Guid、string、数值类型等）会优先从查询字符串、路由参数、表单字段中匹配取值，不会自动读取JSON请求体。
• 只有当参数是自定义复杂类型（包含多个属性的类）时，框架才会根据请求的Content-Type自动从请求体绑定整个对象。

你的代码中fooId和data是独立的简单类型参数，所以框架会去查询字符串中查找对应值，找不到就抛出"Required parameter was not provided from query string"错误。

解决方案 #

推荐两种合规的处理方式：

方式1：用[FromBody]显式指定绑定源 #

给每个需要从请求体读取的参数标记[FromBody]，明确告知框架绑定来源：

private static async Task<Ok> PostVerifyFooAsync(
    [FromBody] Guid fooId,
    [FromBody] string data
)
{
    return TypedResults.Ok();
}

⚠️ 注意：请求体只能被读取一次，若多个参数都标记[FromBody]，可能引发请求体读取异常，因此更推荐下面的方式。

方式2：封装为复杂DTO类（最佳实践） #

创建一个包含所需属性的DTO类，让框架自动绑定整个请求体：

// 定义请求DTO
public class VerifyFooRequest
{
    public Guid FooId { get; set; }
    public string Data { get; set; }
}

// 端点方法接收DTO参数
private static async Task<Ok> PostVerifyFooAsync(VerifyFooRequest request)
{
    // 使用 request.FooId 和 request.Data 处理业务逻辑
    return TypedResults.Ok();
}

这种方式既符合框架默认逻辑，代码结构更清晰，也便于后续扩展请求参数。

为什么框架不自动识别JSON请求体？ #

Minimal API的设计兼顾了灵活性与明确性：

• 简单类型通常用于路由、查询参数这类HTTP API的常见场景，默认绑定这些位置符合常规用法。
• 复杂类型对应完整的请求体数据结构，默认绑定请求体可以避免歧义（比如参数名同时出现在查询字符串和请求体时的优先级问题）。
  因此框架没有设计自动将多个简单类型从请求体绑定的逻辑，而是通过明确规则减少开发中的不确定性。

内容的提问来源于stack exchange，提问作者Learning AWS and PostgreSQL