ASP.NET Core Web API 控制器及方法注解详解

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() { ... }
}

HTTP 动词

[HttpGet], [HttpPost], [HttpPut], [HttpDelete] 等是 [HttpMethod] 的快捷方式。它们通常配合内联路由模板使用，让代码更简洁。

[HttpGet("{id}")] // 映射到 GET api/products/{id}
public IActionResult GetUser(int id) { ... }

[HttpPost("create")] // 映射到 POST api/products/create
public IActionResult CreateProduct([FromBody] Product product) { ... }

// 标记非 Action 方法，防止被路由
[NonAction]
public string GenerateToken() { ... }

2. 参数绑定源

明确数据来源能让接口更健壮。同样属于 Microsoft.AspNetCore.Mvc 命名空间。

• [FromBody]：从请求正文绑定，常用于 JSON/XML 对象。在 [ApiController] 下，复杂类型默认即为此来源。
• [FromQuery]：从 URL 查询字符串绑定，适合简单类型过滤条件。
• [FromRoute]：从路由模板中的 {param} 绑定。
• [FromHeader] / [FromForm]：分别对应请求头和表单数据。
• [FromServices]：通过依赖注入容器解析服务，而非请求数据。

安全提示： 注意 [BindNever] 的使用，它可以防止过度提交攻击（Mass Assignment），避免客户端恶意修改敏感字段（如 IsAdmin）。

public class UserUpdateModel
{
    public string Username { get; set; }

    [BindRequired] // 必须提供 Email
    public string Email { get; set; }

    [BindNever] // 禁止客户端设置此字段
    public bool IsAdmin { get; set; }
}

[HttpPost]
public IActionResult PlaceOrder(Order order, [FromServices] IOrderService service)
{
    service.ProcessOrder(order);
    return Ok();
}

3. 响应类型与格式

规范响应类型有助于前后端协作，特别是生成 Swagger 文档时。

• [Produces]：指定返回的内容类型（MIME 类型）。可作用于控制器或方法。
• [Consumes]：指定接受的内容类型。如果不匹配，框架会返回 415 状态码。
• [ProducesResponseType]：强烈推荐。明确声明方法可能返回的状态码及类型，这对 Swagger 契约至关重要。
• [ProducesDefaultResponseType]：捕获未明确声明的错误响应类型。

[HttpDelete("{id}")]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ProducesDefaultResponseType(typeof(ProblemDetails))]
public IActionResult Delete(int id)
{
    try
    {
        // 删除逻辑
        return NoContent();
    }
    catch (NotFoundException)
    {
        return NotFound();
    }
}

4. 授权与认证

安全是 API 的重中之重，相关注解位于 Microsoft.AspNetCore.Authorization。

• [Authorize]：要求用户登录。可配置策略 (Policy) 或角色 (Roles)。
• [AllowAnonymous]：允许匿名访问，常用于登录注册接口，可覆盖控制器级别的 [Authorize]。
• [RequiredScope]：用于 OAuth2 场景，检查访问令牌是否包含特定作用域。

[ApiController]
[Authorize] // 整个控制器需要登录
[Route("api/[controller]")]
public class SecureController : ControllerBase
{
    [HttpGet("admin")]
    [Authorize(Roles = "Administrator")] // 需特定角色
    public IActionResult AdminOnly() { ... }

    [AllowAnonymous] // 覆盖上方限制
    [HttpGet("public")]
    public IActionResult PublicInfo() { ... }
}

5. Swagger/OpenAPI 文档增强

为了让生成的文档更易读，可以使用 Swashbuckle.AspNetCore.Annotations 提供的注解。

• [SwaggerOperation]：自定义操作摘要、描述和标签。
• [SwaggerResponse]：补充响应细节，如示例值。
• [SwaggerParameter]：为参数添加描述或强制必填。
• [SwaggerSchema]：应用于模型类，定义 Schema 元数据。

[HttpPost]
[SwaggerOperation(
    Summary = "Creates a new product",
    Description = "Requires administrator privileges.",
    OperationId = "CreateProduct",
    Tags = new[] { "Admin" })]
public ActionResult<Product> Create([FromBody] Product product) { ... }

public class Product
{
    [SwaggerSchema("The unique identifier", ReadOnly = true)]
    public int Id { get; set; }

    [SwaggerSchema("The name of the product", Example = "Apple iPhone 13")]
    public string Name { get; set; }
}

掌握这些注解，能让你的 Web API 开发更加规范、安全且易于维护。实际项目中，建议结合 [ApiController] 的全局约定特性，按需细化每个接口的行为。