ASP.NET Core Web API 控制器及方法注解详解
在 ASP.NET Core 开发中,合理使用注解能大幅简化控制器的编写逻辑。这些属性主要用于定义路由、HTTP 方法、参数绑定、响应类型、授权以及 Swagger 文档等,通常位于控制器类或 Action 方法上。
1. 路由与 HTTP 方法
这部分主要涉及 Microsoft.AspNetCore.Mvc 命名空间下的核心注解。
[ApiController]
这是现代 Web API 的标配。应用于控制器类后,它会启用一系列约定行为:
- 自动验证: 模型验证失败时,自动返回
BadRequestResult(400),并包含ModelState错误详情。 - 推断参数源: 复杂类型默认从请求体 (
[FromBody]) 绑定,简单类型默认从查询字符串 ([FromQuery]) 或路由 ([FromRoute]) 获取。 - 错误处理: 4xx 错误响应会自动包含
ProblemDetails格式的错误信息。
路由定义
使用 [Route] 可以灵活定义 URL 模板。它支持占位符如 [controller](控制器名去掉后缀)和 {param}。如果同时定义了控制器级和方法级的路由,框架会进行组合。
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
public class OrdersController : ControllerBase
{
// 组合成 api/v1/orders/5
[HttpGet("{id:int}")]
public IActionResult GetById(int id) { ... }
// 使用控制器前缀:api/v1/orders
[HttpPost]
public IActionResult Create(Order order) { ... }
// 覆盖控制器前缀,使用根级路由
[Route("~/legacy/orders")]
public IActionResult GetLegacyOrders() { ... }
}

