在 ASP.NET Core Web API 开发中,属性(Attribute)是定义路由、参数绑定、响应类型及安全控制的核心机制。它们通常应用于控制器类或 Action 方法上,帮助框架理解如何处理请求和生成响应。下面梳理了 Microsoft.AspNetCore.Mvc 命名空间下的关键特性,涵盖自动验证、模型绑定、响应类型声明及 Swagger 文档增强等实战场景。
1. 路由与 HTTP 方法
这部分主要涉及 Microsoft.AspNetCore.Mvc 命名空间,决定了接口如何被访问以及处理哪种 HTTP 动词。
[ApiController] 这是一个非常实用的特性,建议所有 API 控制器都继承自它。启用后会自动带来几个便利:
- 自动 HTTP 400 响应: 当模型验证失败时,无需手动编写代码,框架会自动返回
BadRequestResult(400),并包含ModelState的错误详情。 - 推断参数源: 复杂类型参数默认从请求体 (
FromBody) 绑定,简单类型默认从查询字符串 (FromQuery) 或路由 (FromRoute) 获取。 - 属性路由要求: 强制要求使用
[Route]或[HttpGet]等属性定义路由,避免隐式路由带来的混乱。 - 错误状态码详细信息: 在 4xx 错误响应中包含
ProblemDetails格式的结构化错误信息。
[Route] 与 HTTP 方法属性
[Route] 用于定义 URL 模板,可作用于控制器(作为前缀)或具体方法。支持 {param} 占位符和 [controller] 动态替换。
HTTP 方法属性如 [HttpGet], [HttpPost] 等本质上是带有固定 HttpMethod 的快捷方式。它们通常配合内联路由模板使用,例如 [HttpGet("{id}")]。
示例:
public class UsersController : ControllerBase
{
// 这是一个 Action 方法,映射到 GET api/users/5
[HttpGet("{id}")]
public IActionResult GetUser(int id)
{
return Ok(new { Id = id });
}
// 这是一个公共辅助方法,但不是 Action,不会被路由
[NonAction]
public string GeneratePasswordResetToken()
{
return "token";
}
}

