.NET Web API 核心注解属性指南
在 .NET Web API 开发中，控制器（Controller）和 Action 方法上的注解决定了路由规则、参数来源、响应格式以及安全策略。合理使用这些属性能让代码更简洁、规范且易于维护。
1. 路由与 HTTP 方法
这部分主要涉及 Microsoft.AspNetCore.Mvc 命名空间下的基础注解。
[ApiController]
应用于控制器类时，它会启用一系列针对 API 的默认约定：
- 自动验证：模型验证失败时自动返回 400 状态码及错误详情。
- 推断参数源：复杂类型默认从请求体绑定 (
FromBody)，简单类型默认从查询字符串或路由绑定。 - 强制属性路由：要求必须使用
[Route]等属性定义路由，不能仅依赖约定式路由。 - 错误处理：在 4xx 错误中包含
ProblemDetails格式信息。
[Route] 与 HTTP 方法属性
[Route] 用于定义 URL 模板，可作用于控制器（作为前缀）或具体方法。支持 {param} 占位符和版本控制。
HTTP 方法属性如 [HttpGet], [HttpPost] 等是 [HttpMethod] 的快捷方式，指定响应哪个动词。它们通常配合内联路由模板使用。
注意：在
[ApiController]下，如果未显式指定路由，框架可能会报错，建议始终明确声明路由。
public class UsersController : ControllerBase
{
// 映射到 GET api/users/5
[HttpGet("{id}")]
public IActionResult GetUser(int id)
{
// ... 业务逻辑
}
// 标记为非 Action 方法，防止被路由
[NonAction]
public string GeneratePasswordResetToken()
{
return "token";
}
}
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
public :
{
[]
{ ... }
[]
{ ... }
[]
{ ... }
}
