.NET Web API 核心注解实战指南
在构建 .NET Web API 时,控制器(Controller)和 Action 方法上的注解决定了接口的路由规则、参数来源、响应格式以及安全策略。理解这些属性不仅能减少样板代码,还能让 Swagger 文档更精准。
1. 路由与 HTTP 方法
Microsoft.AspNetCore.Mvc 命名空间下的注解主要处理请求如何映射到代码。
[ApiController] 与约定优先
将 [ApiController] 应用于控制器类,可以启用一系列针对 API 的默认行为:
- 自动验证:模型验证失败时自动返回
400 Bad Request及错误详情。 - 推断参数源:复杂类型默认从请求体读取 (
[FromBody]),简单类型默认从查询字符串或路由读取。 - 强制属性路由:要求必须使用
[Route]等定义路径。
[ApiController]
[Route("api/[controller]")] // 必需属性路由
public class ProductsController : ControllerBase
{
// ... Action 方法
}
路由模板与 HTTP 动词
[Route] 定义 URL 结构,支持 {param} 占位符。HTTP 动词属性(如 [HttpGet], [HttpPost])则指定方法响应的请求方式。
[HttpGet("{id:int}")] // 匹配 GET api/products/5
public IActionResult GetById(int id)
{
// ...
}
[HttpPost("create")]
public IActionResult Create([FromBody] Product product)
{
// ...
}
若需同时响应多种 HTTP 方法,可使用 [AcceptVerbs],不过在新版中通常直接定义多个 Action 或使用 [HttpMethod]。
2. 参数绑定源
明确数据从哪里来是 API 开发的关键。[ApiController] 虽能智能推断,但显式标注能让意图更清晰。

