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

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

一、[FromRoute]:从路由模板提取参数

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

用法:假设我们有一个路由模板api/users/{userId},其中{userId}是动态部分。对应的控制器方法可以这样声明:

[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可能包含查询参数:

[HttpGet("api/users")]
public IActionResult GetUsers([FromQuery]string sortOrder = "desc", [FromQuery]int page = 1, [FromQuery]int pageSize = 20)
{
    // 使用 sortOrder, page, pageSize 参数执行查询并返回结果
}

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

三、[FromBody]:从请求主体(Body)提取参数

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

用法:假设我们有一个API端点用于创建新用户,客户端以JSON格式将用户信息发送到服务器:

[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开发跳槽;加微信xbhpnet入群求职技术交流",
}

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的关键步骤之一。本文仅供参考。

来源公众号↑↑↑:DotNet开发跳槽❀    
posted @ 2024-04-16 12:37  翔星  阅读(213)  评论(1编辑  收藏  举报