.NET Web API 控制器常用注解属性详解
在 .NET Core 或 .NET 5+ 开发中，Web API 控制器的行为很大程度上由特性（Attribute）定义。这些注解不仅决定了路由规则、参数来源和响应格式，还涉及安全认证与文档生成。下面结合实战场景，梳理 Microsoft.AspNetCore.Mvc 及相关命名空间下的核心注解。
1. 路由与 HTTP 方法
路由是 API 的入口，而 HTTP 方法定义了操作类型。
[ApiController] 与自动约定
将 [ApiController] 应用于控制器类时，框架会启用一系列针对 API 的默认行为：
- 自动模型验证：当模型验证失败时，自动返回
400 Bad Request及ModelState详情。 - 推断参数源：复杂类型参数默认来自请求体 (
[FromBody])，简单类型默认来自查询字符串 ([FromQuery])。 - 错误处理：在 4xx 错误中包含
ProblemDetails格式信息。 - 强制属性路由：通常要求使用
[Route]或[HttpGet]等显式定义路由。
路由模板与 HTTP 动词
[Route] 用于定义 URL 路径，支持 {param} 占位符及 [controller] 等系统变量。配合 [HttpGet], [HttpPost] 等快捷方式可指定具体 HTTP 方法。
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
// 映射到 GET api/products/5
[HttpGet("{id:int}")]
public IActionResult GetById(int id)
{
// ...
}
// 映射到 POST api/products/create
[HttpPost("create")]
public IActionResult Create([FromBody] Product product)
{
// ...
}
// 非 Action 方法需标记，防止被误认为端点
[]
=> ;
}
