ASP.NET Core Web API 控制器与 Action 常用注解详解 | 极客日志

C#

ASP.NET Core Web API 控制器与 Action 常用注解详解

ASP.NET Core Web API 开发中，注解属性是定义路由、参数绑定及安全控制的核心机制。梳理了 Microsoft.AspNetCore.Mvc 命名空间下的关键特性，涵盖自动验证、模型绑定、响应类型声明及 Swagger 文档增强等实战场景，帮助开发者构建规范且易维护的后端服务。

HadoopMan发布于 2026/3/15更新于 2026/4/251 浏览

在 ASP.NET Core Web API 开发中，属性（Attribute）是定义路由、参数绑定、响应类型及安全控制的核心机制。它们通常应用于控制器类或 Action 方法上，帮助框架理解如何处理请求和生成响应。下面梳理了 Microsoft.AspNetCore.Mvc 命名空间下的关键特性，涵盖自动验证、模型绑定、响应类型声明及 Swagger 文档增强等实战场景。

1. 路由与 HTTP 方法

这部分主要涉及 Microsoft.AspNetCore.Mvc 命名空间，决定了接口如何被访问以及处理哪种 HTTP 动词。

[ApiController] 这是一个非常实用的特性，建议所有 API 控制器都继承自它。启用后会自动带来几个便利：

自动 HTTP 400 响应： 当模型验证失败时，无需手动编写代码，框架会自动返回 BadRequestResult (400)，并包含 ModelState 的错误详情。
推断参数源： 复杂类型参数默认从请求体 (FromBody) 绑定，简单类型默认从查询字符串 (FromQuery) 或路由 (FromRoute) 获取。
属性路由要求： 强制要求使用 [Route] 或 [HttpGet] 等属性定义路由，避免隐式路由带来的混乱。
错误状态码详细信息： 在 4xx 错误响应中包含 ProblemDetails 格式的结构化错误信息。

[Route] 与 HTTP 方法属性 [Route] 用于定义 URL 模板，可作用于控制器（作为前缀）或具体方法。支持 {param} 占位符和 [controller] 动态替换。 HTTP 方法属性如 [HttpGet], [HttpPost] 等本质上是带有固定 HttpMethod 的快捷方式。它们通常配合内联路由模板使用，例如 [HttpGet("{id}")]。

示例：

public class UsersController : ControllerBase
{
    // 这是一个 Action 方法，映射到 GET api/users/5
    [HttpGet("{id}")]
    public IActionResult GetUser(int id)
    {
        return Ok(new { Id = id });
    }

    // 这是一个公共辅助方法，但不是 Action，不会被路由
    [NonAction]
    public string GeneratePasswordResetToken()
    {
        return "token";
    }
}

[AcceptVerbs("GET", "HEAD")]
public IActionResult GetInfo(int id)
{
    // 响应 GET 和 HEAD 请求
    return Ok();
}

[ApiController]
[Route("api/[controller]")] // 控制器级路由，必须属性路由
public class ProductsController : ControllerBase
{
    [HttpGet] // 映射到 GET api/products
    public IEnumerable<Product> GetAll()
    {
        return new List<Product>();
    }

    [HttpGet("{id}")] // 映射到 GET api/products/5
    public ActionResult<Product> GetById(int id)
    {
        return NotFound();
    }

    [HttpPost("create")] // 映射到 POST api/products/create
    public IActionResult CreateProduct([FromBody] Product product)
    {
        return CreatedAtAction(nameof(GetById), new { id = 1 }, product);
    }

    [HttpPut("{id}")] // 映射到 PUT api/products/5
    public IActionResult UpdateProduct(int id, [FromBody] Product product)
    {
        return NoContent();
    }

    [HttpDelete("{id}")] // 映射到 DELETE api/products/5
    public IActionResult DeleteProduct(int id)
    {
        return NoContent();
    }
}

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

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

    [BindNever] // 防止客户端设置 IsAdmin 属性
    public bool IsAdmin { get; set; }
}

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

[HttpPost("upload")]
public IActionResult UploadFile([FromForm] IFormFile file, [FromForm] string description)
{
    // 处理文件上传逻辑
    return Ok();
}

[HttpDelete("{id}")]
[ProducesResponseType(StatusCodes.Status204NoContent)] // 删除成功
[ProducesResponseType(StatusCodes.Status404NotFound)] // 找不到资源
[ProducesDefaultResponseType(typeof(ProblemDetails))] // 其他错误
public IActionResult Delete(int id)
{
    try
    {
        // 删除逻辑
        return NoContent();
    }
    catch (NotFoundException)
    {
        return NotFound();
    }
}

[HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status200OK, Type = typeof(Product))]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<Product> GetById(int id)
{
    if (id <= 0) return BadRequest("ID must be positive");
    var product = _repository.GetProduct(id);
    if (product == null) return NotFound();
    return product;
}

[ApiController]
[Authorize] // 整个控制器需要登录
[Route("api/[controller]")]
public class SecureController : ControllerBase
{
    [HttpGet("userinfo")]
    public IActionResult GetUserInfo() { ... }

    [HttpGet("admin")]
    [Authorize(Roles = "Administrator")] // 需要登录且角色为 Administrator
    public IActionResult AdminOnly() { ... }
}

[AllowAnonymous] // 覆盖控制器的 [Authorize]
[HttpGet("public")]
public IActionResult PublicInfo() { ... }

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

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

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