在 ASP.NET Core Web API 开发中，合理使用控制器注解能显著提升代码规范性和可维护性。这些属性通常应用于控制器类或 Action 方法上，用于定义路由、HTTP 方法、参数绑定、响应类型、授权以及 Swagger 文档等。
路由与 HTTP 方法
Microsoft.AspNetCore.Mvc 命名空间下提供了最基础的路由控制能力。
[ApiController] 这是现代 Web API 的基石。将其应用于控制器类后，框架会自动启用一系列约定行为：模型验证失败时自动返回 400 状态码及错误详情；智能推断复杂类型参数来自请求体（FromBody），简单类型来自查询字符串或路由；同时强制要求使用特性路由（如 [Route]）。
[Route]
用于定义 URL 模板。可以放在控制器级别作为前缀，也可以放在具体方法上覆盖。支持 {param} 占位符和 [controller] 等系统变量。通过 Name 参数可以为路由命名，方便后续生成链接。
HTTP 方法特性
包括 [HttpGet], [HttpPost], [HttpPut], [HttpDelete] 等。它们本质上是带有固定 HTTP 动词的快捷方式。通常配合内联路由模板使用，例如 [HttpGet("{id}")] 直接映射到 GET api/products/5。
示例：
public class UsersController : ControllerBase
{
// 这是一个 Action 方法，映射到 GET api/users/{id}
[HttpGet("{id}")]
public IActionResult GetUser(int id)
{
// ...
}
// 这是一个公共辅助方法，但不是 Action
[NonAction]
public string GeneratePasswordResetToken()
{
return "";
}
}
[AcceptVerbs] 允许一个方法响应多个 HTTP 方法，例如同时处理 GET 和 HEAD 请求。不过在 .NET Core 中更推荐直接使用对应的 HttpGet/HttpHead 组合。
参数绑定源
默认情况下，框架会根据参数类型自动推断来源，但显式指定往往更清晰且安全。
- [FromBody]: 从请求正文绑定，常用于 JSON/XML 对象。在
[ApiController]模式下，复杂类型默认即为此来源。 - [FromQuery]: 从 URL 查询字符串绑定，适合分页、过滤等简单参数。
- [FromRoute]: 从路径参数绑定，如
/api/users/123中的 。
