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 查询字符串获取，适合分页、筛选参数。
