ASP.NET Core Web API 控制器与方法注解属性详解
在构建 RESTful 接口时,合理使用特性(Attribute)注解能显著减少样板代码,提升接口的规范性与安全性。这些注解主要分布在 Microsoft.AspNetCore.Mvc 和 Microsoft.AspNetCore.Authorization 命名空间中,用于定义路由、参数绑定、响应格式及权限控制。
路由与 HTTP 方法
路由配置是 API 的入口。[ApiController] 是一个非常有用的特性,将其应用于控制器类后,框架会自动启用一系列约定行为:
- 自动模型验证:当请求数据不符合模型约束时,直接返回
400 Bad Request并附带详细的错误信息。 - 智能参数推断:复杂类型默认从请求体读取 (
FromBody),简单类型默认从查询字符串或路由读取。 - 强制属性路由:要求必须使用
[Route]等显式定义路由,避免隐式路由带来的歧义。
配合 [Route] 使用,可以灵活定义 URL 模板。例如,在控制器级别定义前缀,在 Action 方法上追加路径:
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
// 映射到 GET api/products/5
[HttpGet("{id}")]
public ActionResult<Product> GetById(int id)
{
// ... 业务逻辑
}
// 映射到 POST api/products/create
[HttpPost("create")]
public IActionResult Create([FromBody] Product product)
{
return Ok();
}
}
对于需要支持多种 HTTP 动词的方法,可以使用 [AcceptVerbs],但在新版中更推荐直接使用 [HttpGet]、[HttpPost] 等快捷方式。注意 [NonAction] 可用于标记公共辅助方法,防止其被误识别为端点。
参数绑定源
明确数据来源是处理请求的关键。ASP.NET Core 提供了丰富的绑定来源注解:
- [FromBody]:适用于 JSON/XML 请求体,通常绑定复杂对象。
- [FromQuery]:从 URL 查询字符串获取,适合分页、筛选参数。

