.NET WebAPI中FromRoute、FromQuery、FromBody的关键角色与用法

.NET WebAPI作为一种构建RESTful服务的强大工具，为开发者提供了便捷的方式来定义、处理HTTP请求并返回响应。在设计API接口时，正确地接收和解析客户端发送的数据至关重要。.NET WebAPI提供了一系列特性，如[FromRoute]、[FromQuery]和[FromBody]，用于指示控制器方法应如何从不同的请求源提取参数。

| 列名 | 列名 |
| --- | --- |
| FromBody | 当请求的 content-type 为 application/json 时，可以不加上这个特性，因为当入参类型为实体类时，系统默认从请求体（body）中获取数据 |
| FromForm | 当请求属于表单提交，也就是 content-type 为 application/x-www-form-urlencoded，则必须给参数加上 FromForm 特性，否者会报 400 错误 |
| FromQuery  | 获取地址烂参数，当接口参数是一个实体类时，建议必须加上该特性 |
| FromHeader | 获取请求头参数 |
| FromRoute | 获取路由参数 |

# 一、[FromRoute]：从路由模板提取参数
- 作用：
[FromRoute]属性用于标识那些应从HTTP请求的路由数据中提取的参数。当客户端访问一个URL，其路径部分可能包含动态占位符（通常称为路由参数）。[FromRoute]属性指示ASP.NET Core框架应将这些路由参数值绑定到控制器方法的相应参数上。

- 用法：
假设我们有一个路由模板api/users/{userId}，其中{userId}是动态部分。对应的控制器方法可以这样声明
```java
[HttpGet("api/users/{userId}")]
public IActionResult GetUser([FromRoute]int userId)
{
    // 使用 userId 参数查询用户信息并返回结果
}
```

userId参数被[FromRoute]装饰，表示它应从请求的URL路径（即路由数据）中获取其值。当客户端访问如 https://example.com/api/users/123 这样的URL时userId参数会被自动赋值为123。

# 二、[FromQuery]：从查询字符串提取参数
- 作用：
[FromQuery]属性指示控制器方法应从HTTP请求的查询字符串中提取参数。查询字符串是URL末尾以问号(?)开始，由键值对组成的部分，例如?sortOrder=asc&page=2。使用[FromQuery]，可以轻松地将这些键值对映射到方法参数。

- 用法：
考虑一个API端点用于分页和排序用户列表，其URL可能包含查询参数：
```java
[HttpGet("api/users")]
public IActionResult GetUsers([FromQuery]string sortOrder = "desc", [FromQuery]int page = 1, [FromQuery]int pageSize = 20)
{
    // 使用 sortOrder, page, pageSize 参数执行查询并返回结果
}
```

在这个例子中，sortOrder、page和pageSize参数都标记为[FromQuery]，表示它们的值应从请求的查询字符串中提取。客户端可以通过访问类似https://example.com/api/users?sortOrder=asc&page=2 的URL来指定排序方式和分页信息。

# 三、[FromBody]：从请求主体（Body）提取参数
- 作用：
[FromBody]属性指示ASP.NET Core框架应从HTTP请求的主体（Body）中反序列化并提取参数。这通常用于处理POST、PUT等方法中携带的复杂数据，如JSON或XML格式的内容。当客户端以请求体的形式发送非简单类型的数据时，[FromBody]是必不可少的。

- 用法：
假设我们有一个API端点用于创建新用户，客户端以JSON格式将用户信息发送到服务器
```java
[HttpPost("api/users")]
public IActionResult CreateUser([FromBody]User user)
{
    // 使用 user 参数创建新用户并返回结果
}
public class User
{
   public string Username { get; set; }
   public string Password { get; set; }
   public string Notes { get; set; }
}
```

在此示例中，User类实例作为CreateUser方法的参数，并用[FromBody]修饰。当客户端发送如下JSON到POST /api/users：
{
    "username": "DotNET开发跳槽",
    "password": "s3cr3tP@ssw0rd"
    "Notes": "欢迎关注公众号：DotNET开发跳槽",
}
ASP.NET Core会自动将JSON内容反序列化为User对象，并将其赋值给user参数。

结语
[FromRoute]、[FromQuery]和[FromBody]是.NET WebAPI中用于从不同请求源提取参数的核心特性。本文介绍了三者在.NET WebAPI中的角色和用法，希望给大家带来收获。

当然也可以不添加这些特性，若不使用[FromRoute]、[FromQuery]和[FromBody]等特性来明确指示参数来源，ASP.NET Core WebAPI会遵循默认绑定规则尝试自动绑定请求数据。虽然这种方式在简单场景下可能工作，但它可能导致代码可读性降低、绑定行为不确定性增加以及限制API设计的灵活性与可扩展性。因此，为了确保代码清晰、易于理解和维护，以及请求数据绑定的确定性和一致性，建议在编写控制器方法时始终显式使用这些特性指定参数来源。

理解并恰当使用这些属性，能够确保您的WebAPI接口准确、高效地处理客户端请求，实现清晰、语义化的API设计。根据请求数据的位置和格式，选择合适的属性进行参数绑定，是构建健壮、通用RESTful API的关键步骤之一。本文仅供参考。