当前位置： 首页 > news >正文

基于.Net的Web API 控制器及方法相关注解属性

news 2025/7/2 8:38:04

在这里插入图片描述

文章目录

      • 1. 路由与 HTTP 方法 (`Microsoft.AspNetCore.Mvc` 命名空间)
      • 2. 参数绑定源 (`Microsoft.AspNetCore.Mvc` 命名空间)
      • 3. 响应类型与格式 (`Microsoft.AspNetCore.Mvc` 命名空间)
      • 4. 授权与认证 (`Microsoft.AspNetCore.Authorization` 命名空间)
      • 5. Swagger/OpenAPI 文档增强 (`Swashbuckle.AspNetCore.Annotations` 或 `Microsoft.AspNetCore.Mvc`)

在这里插入图片描述

这些属性主要用于定义 API 的路由、HTTP 方法、参数绑定、响应类型、授权、Swagger 文档等，通常位于控制器类或 Action 方法上。

1. 路由与 HTTP 方法 (Microsoft.AspNetCore.Mvc 命名空间)

  • [ApiController]

    • 作用： 应用于控制器类。启用 API 特定的约定和行为：
      • 自动 HTTP 400 响应： 当模型验证失败时，自动返回 BadRequestResult (400)，包含 ModelState 错误详情。
      • 推断参数源： 自动推断复杂类型参数来自请求体 ([FromBody])，简单类型来自查询字符串 ([FromQuery]) 或路由 ([FromRoute])。
      • 属性路由要求： 要求控制器使用 [Route] 或 [HttpGet] 等属性定义路由。
      • 错误状态码详细信息： 在 4xx 错误响应中包含 ProblemDetails 格式的错误信息。
    • 示例：
      [ApiController]
[Route("api/[controller]")] // 必需属性路由
public class ProductsController : ControllerBase
{// ...
}

  • [Route]

    • 作用： 定义控制器或 Action 方法的 URL 路由模板。可应用于控制器（为所有 Action 方法设置前缀）或 Action 方法。
    • 参数：
      • Template (必填): URL 路由模板字符串。可以使用 [controller]（控制器名去掉 “Controller” 后缀）、[action]（方法名）占位符。模板中可用 {param} 定义路由参数。
      • Name (可选): 为路由指定一个唯一名称，用于生成 URL (IUrlHelper 或链接)。
      • Order (可选): 路由匹配的顺序（数字越小优先级越高）。
    • 示例：
      [ApiController]
[Route("api/v{version:apiVersion}/[controller]")] // 控制器级路由，带版本
public class OrdersController : ControllerBase
{[HttpGet("{id:int}")] // Action 级路由，组合成 api/v1/orders/5public IActionResult GetById(int id) { ... }[HttpPost] // 使用控制器路由前缀：api/v1/orderspublic IActionResult Create(Order order) { ... }[Route("~/legacy/orders")] // 覆盖控制器前缀，使用根级路由 /legacy/orderspublic IActionResult GetLegacyOrders() { ... }
}

  • HTTP 方法属性 ([HttpGet], [HttpPost], [HttpPut], [HttpDelete], [HttpPatch], [HttpHead], [HttpOptions])

    • 作用： 指定 Action 方法响应哪个 HTTP 方法（动词）。它们本质上是带有固定 HttpMethod 的 [HttpMethod] 属性的快捷方式。通常与 [Route] 或内联路由模板一起使用。
    • 参数：
      • Template (可选): 内联的路由模板字符串。如果提供，它会覆盖或附加到控制器路由模板。
      • Name (可选): 路由名称。
      • Order (可选): 路由顺序。
    • 示例：
      [HttpGet] // 映射到 GET api/products
public IEnumerable<Product> GetAll() { ... }[HttpGet("{id}")] // 映射到 GET api/products/5
public ActionResult<Product> GetById(int id) { ... }[HttpPost("create")] // 映射到 POST api/products/create
public IActionResult CreateProduct([FromBody] Product product) { ... }[HttpPut("{id}")] // 映射到 PUT api/products/5
public IActionResult UpdateProduct(int id, [FromBody] Product product) { ... }[HttpDelete("{id}")] // 映射到 DELETE api/products/5
public IActionResult DeleteProduct(int id) { ... }

  • [AcceptVerbs]

    • 作用： 允许 Action 方法响应多个 HTTP 方法。指定一个或多个 HTTP 方法字符串（如 "GET", "POST", "PATCH"）。
    • 参数：
      • verbs (必填): 允许的 HTTP 方法列表。
    • 示例：
      [AcceptVerbs("GET", "HEAD")] // 响应 GET 和 HEAD 请求
public IActionResult GetInfo(int id) { ... }

  • [NonAction]

    • 作用： 标记控制器类中的某个公共方法不是一个 Action 方法。防止 MVC 框架将其视为可路由的 HTTP 端点。
    • 示例：
      public class UsersController : ControllerBase
{// 这是一个 Action 方法[HttpGet("{id}")]public IActionResult GetUser(int id) { ... }// 这是一个公共辅助方法，但不是 Action[NonAction]public string GeneratePasswordResetToken() { ... }
}

2. 参数绑定源 (Microsoft.AspNetCore.Mvc 命名空间)

  • [FromBody]

    • 作用： 指示参数应从 HTTP 请求的正文中绑定。通常用于绑定复杂的 JSON/XML 对象。在 [ApiController] 中，复杂类型参数默认使用此来源。
    • 示例：
      [HttpPost]
public IActionResult Create([FromBody] Product product) // 从请求体 JSON 绑定
{// ...
}

  • [FromQuery]

    • 作用： 指示参数应从 URL 查询字符串中绑定。在 [ApiController] 中，简单类型参数默认使用此来源。
    • 示例：
      [HttpGet("search")]
public IActionResult SearchProducts([FromQuery] string name, [FromQuery] int? minPrice)
{// GET /api/products/search?name=apple&minPrice=10
}

  • [FromRoute]

    • 作用： 指示参数应从 URL 路由数据中绑定（由路由模板中的 {param} 定义）。在 [ApiController] 中，如果路由模板中有匹配名称的参数，默认使用此来源。
    • 示例：
      [HttpGet("{id:int}")]
public IActionResult GetById([FromRoute] int id) // 从路由 /api/products/5 中绑定 id=5
{// ...
}

  • [FromHeader]

    • 作用： 指示参数应从 HTTP 请求头中绑定。
    • 示例：
      [HttpGet]
public IActionResult Get([FromHeader(Name = "X-Client-Version")] string clientVersion)
{// 从请求头 X-Client-Version 获取值
}

  • [FromForm]

    • 作用： 指示参数应从 HTTP 请求的已提交表单数据中绑定。常用于 multipart/form-data 或 application/x-www-form-urlencoded 内容类型。
    • 示例：
      [HttpPost("upload")]
public IActionResult UploadFile([FromForm] IFormFile file, [FromForm] string description)
{// ...
}

  • [FromServices]

    • 作用： 指示参数应通过依赖注入 (DI) 容器解析获得，而不是从请求中绑定。用于在 Action 方法中注入服务。
    • 示例：
      [HttpPost]
public IActionResult PlaceOrder(Order order, [FromServices] IOrderService orderService)
{orderService.ProcessOrder(order);return Ok();
}

  • [BindRequired] / [BindNever]

    • 作用：
      • [BindRequired]: 指示参数是必需的，如果无法绑定（如从查询字符串缺少值），则模型验证会失败。
      • [BindNever]: 指示参数应被完全忽略，不进行绑定。常用于防止过度提交攻击（Mass Assignment）。
    • 示例：
      public class UserUpdateModel
{public string Username { get; set; }[BindRequired] // 更新时必须提供 Emailpublic string Email { get; set; }[BindNever] // 防止客户端设置 IsAdmin 属性public bool IsAdmin { get; set; }
}

3. 响应类型与格式 (Microsoft.AspNetCore.Mvc 命名空间)

  • [Produces]

    • 作用： 应用于控制器或 Action 方法，指定 Action 方法返回的响应内容类型（MIME 类型，如 "application/json", "application/xml"）。影响 Content-Type 响应头和客户端内容协商。
    • 参数：
      • contentType (必填): 内容类型字符串。
      • Type (可选): 返回对象类型的 Type (常用于 Swagger 文档)。
      • StatusCodes (可选): 关联的状态码数组 (常用于 Swagger 文档)。
    • 示例：
      [ApiController]
[Route("api/[controller]")]
[Produces("application/json")] // 控制器级：所有 Action 默认生成 JSON
public class ProductsController : ControllerBase
{[HttpGet("{id}")][Produces("application/xml")] // 覆盖控制器设置，此 Action 生成 XMLpublic Product GetById(int id) { ... }[HttpGet][Produces("application/json", "application/xml")] // 支持 JSON 和 XML 内容协商public IEnumerable<Product> GetAll() { ... }
}

  • [Consumes]

    • 作用： 应用于控制器或 Action 方法，指定 Action 方法接受的请求内容类型（MIME 类型）。用于内容协商，如果请求的 Content-Type 不匹配，框架会返回 415 Unsupported Media Type。
    • 参数：
      • contentType (必填): 内容类型字符串。
    • 示例：
      [HttpPost]
[Consumes("application/json")] // 只接受 Content-Type 为 application/json 的请求
public IActionResult Create([FromBody] Product product) { ... }[HttpPost("upload")]
[Consumes("multipart/form-data")] // 接受文件上传
public IActionResult Upload([FromForm] IFormFile file) { ... }

  • [ProducesResponseType]

    • 作用： 强烈推荐使用！ 指定 Action 方法返回的特定 HTTP 状态码及其关联的响应类型。主要用于：
      1. Swagger/OpenAPI 文档生成： 为工具（如 SwaggerUI）提供清晰的 API 契约。
      2. 增强代码可读性： 明确说明方法可能返回哪些状态码。
    • 参数：
      • statusCode (必填): HTTP 状态码（如 200, 201, 400, 404, 500）。建议使用 StatusCodes 常量（如 StatusCodes.Status200OK）。
      • Type (可选): 成功响应（2xx）时返回的对象类型。对于错误响应（4xx/5xx），通常是 ProblemDetails 或 string。
      • ContentType (可选): 响应的内容类型。
    • 示例：
      [HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status200OK, Type = typeof(Product))] // 成功返回 Product
[ProducesResponseType(StatusCodes.Status404NotFound)] // 找不到资源
[ProducesResponseType(StatusCodes.Status400BadRequest)] // 无效请求（如 id 格式错误）
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;
}[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created, Type = typeof(Product))] // 创建成功，返回新资源
[ProducesResponseType(StatusCodes.Status400BadRequest, Type = typeof(ValidationProblemDetails))] // 验证失败，返回 ProblemDetails
public async Task<ActionResult<Product>> Create([FromBody] Product product)
{if (!ModelState.IsValid) return BadRequest(ModelState); // [ApiController] 自动处理为 400 + ValidationProblemDetailsvar createdProduct = await _repository.AddProductAsync(product);return CreatedAtAction(nameof(GetById), new { id = createdProduct.Id }, createdProduct); // 201 Created
}

  • [ProducesDefaultResponseType]

    • 作用： 当无法匹配其他 [ProducesResponseType] 指定的状态码时，指定一个默认的响应类型。常用于捕获未明确声明的错误（如 500 Internal Server Error）。
    • 参数：
      • Type (可选): 默认响应的对象类型（通常是 ProblemDetails）。
    • 示例：
      [HttpDelete("{id}")]
[ProducesResponseType(StatusCodes.Status204NoContent)] // 删除成功
[ProducesResponseType(StatusCodes.Status404NotFound)] // 找不到资源
[ProducesDefaultResponseType(typeof(ProblemDetails))] // 其他错误（如服务器异常）
public IActionResult Delete(int id)
{try{// ... 删除逻辑，可能抛出异常return NoContent();}catch (NotFoundException){return NotFound();}// 其他异常会被 [ApiController] 捕获并返回 500 + ProblemDetails
}

4. 授权与认证 (Microsoft.AspNetCore.Authorization 命名空间)

  • [Authorize]

    • 作用： 要求用户必须经过认证（登录）才能访问该控制器或 Action 方法。如果未认证，返回 401 Unauthorized。可应用于控制器（保护所有方法）或单个 Action 方法。
    • 参数：
      • AuthenticationSchemes (可选): 指定使用的认证方案（如 "Bearer", "Cookies"）。
      • Policy (可选): 指定授权策略名称（需要在 Startup.cs 中配置策略）。
      • Roles (可选): 指定允许访问的用户角色（逗号分隔）。用户需要拥有其中至少一个角色。
    • 示例：
      [ApiController]
[Authorize] // 整个控制器需要登录
[Route("api/[controller]")]
public class SecureController : ControllerBase
{[HttpGet("userinfo")]public IActionResult GetUserInfo() { ... } // 需要登录[HttpGet("admin")][Authorize(Roles = "Administrator")] // 需要登录且角色为 Administratorpublic IActionResult AdminOnly() { ... }
}[AllowAnonymous] // 覆盖控制器的 [Authorize]，允许匿名访问
[HttpGet("public")]
public IActionResult PublicInfo() { ... }

  • [AllowAnonymous]

    • 作用： 允许匿名用户访问被 [Authorize] 保护的控制器或 Action 方法。通常用于登录、注册等不需要认证的接口。
    • 示例： 见上面 [Authorize] 示例中的 PublicInfo 方法。

  • [Authorize(Policy = "...")]

    • 作用： 使用自定义授权策略进行访问控制。策略在 Startup.cs 的 ConfigureServices 中使用 services.AddAuthorization 配置，可以包含复杂的授权要求（如年龄限制、声明要求、自定义处理程序）。
    • 示例：
      // Startup.cs
services.AddAuthorization(options =>
{options.AddPolicy("Over18", policy => policy.RequireAssertion(context =>context.User.HasClaim(c => (c.Type == "Age" && int.Parse(c.Value) >= 18)));options.AddPolicy("CanDelete", policy => policy.RequireClaim("Permission", "Delete"));
});// Controller
[HttpDelete("{id}")]
[Authorize(Policy = "Over18")] // 要求年龄 >= 18
[Authorize(Policy = "CanDelete")] // 要求拥有 "Delete" 权限声明 (可以组合多个 [Authorize])
public IActionResult Delete(int id) { ... }

  • [RequiredScope] (通常用于 Azure AD / Microsoft Identity Platform)

    • 作用： 要求请求的访问令牌 (access_token) 必须包含指定的作用域 (Scope)。这是实现 OAuth2 权限控制的关键。
    • 参数：
      • RequiredScopes (必填): 要求的作用域数组。
    • 示例：
      [HttpGet("reports")]
[RequiredScope("Reports.Read", "Reports.ReadWrite")] // 需要 Reports.Read 或 Reports.ReadWrite 权限
public IActionResult GetReports() { ... }

5. Swagger/OpenAPI 文档增强 (Swashbuckle.AspNetCore.Annotations 或 Microsoft.AspNetCore.Mvc)

  • [SwaggerOperation] (Swashbuckle)

    • 作用： 为特定的 API 操作（Action 方法）添加摘要 (Summary) 和详细描述 (Description)。
    • 参数：
      • Summary: 操作的简短摘要。
      • Description: 操作的详细描述。
      • OperationId: 自定义操作的唯一标识符（覆盖默认生成）。
      • Tags: 自定义操作的标签（覆盖默认的控制器名）。
    • 示例：
      [HttpPost]
[SwaggerOperation(Summary = "Creates a new product",Description = "Requires administrator privileges. Returns the created product with its generated ID.",OperationId = "CreateProduct",Tags = new[] { "Admin" })]
public ActionResult<Product> Create([FromBody] Product product) { ... }

  • [SwaggerResponse] (Swashbuckle)

    • 作用： 替代或补充 [ProducesResponseType]，为 Swagger 提供更详细的响应信息（如响应头、示例）。与 [ProducesResponseType] 通常一起使用或单独使用。
    • 参数：
      • statusCode (必填): HTTP 状态码。
      • Type (可选): 响应体类型。
      • Description (可选): 响应的描述。
      • ContentTypes (可选): 响应的内容类型。
    • 示例：
      [HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status200OK)] // MVC 行为
[SwaggerResponse(200, "The product was found", typeof(Product))] // Swagger 文档增强
[SwaggerResponse(404, "The product does not exist", typeof(NotFoundResult))]
public ActionResult<Product> GetById(int id) { ... }

  • [SwaggerParameter] (Swashbuckle)

    • 作用： 为参数添加描述或指定其是否必需（覆盖默认推断）。
    • 参数：
      • Name: 参数名称。
      • Description: 参数描述。
      • Required: 是否必需（覆盖默认）。
      • In: 参数位置 (ParameterLocation.Query, .Path, .Header, .Body)，覆盖默认推断。
    • 示例：
      [HttpGet("search")]
public IActionResult Search([FromQuery, SwaggerParameter("Name of the product to search for", Required = true)] string name,[FromQuery, SwaggerParameter("Minimum price filter")] decimal? minPrice)
{ ... }

  • [SwaggerSchema] (Swashbuckle)

    • 作用： 应用于模型类或属性，为 Swagger Schema 提供额外信息（如描述、示例值、是否只读/必填）。
    • 参数：
      • Description: 模型或属性的描述。
      • ReadOnly: 是否只读（在响应中出现，不应在请求中发送）。
      • Required: 是否必需（覆盖数据注解的 [Required] 对于 Swagger 的影响）。
      • Example: 提供示例值。
    • 示例：
      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; }[SwaggerSchema("The price in USD", Format = "decimal")]public decimal Price { get; set; }
}

  • [ProducesErrorResponseType] (AspNetCore.Mvc) - 与 Swagger 配合

    • 作用： 当与 [ProducesDefaultResponseType] 或特定错误 [ProducesResponseType] 结合使用时，明确告知 Swagger 默认错误响应的类型（通常是 ProblemDetails 或 HttpValidationProblemDetails）。
    • 示例：
      [ApiController]
[ProducesErrorResponseType(typeof(ProblemDetails))] // 告诉 Swagger 默认错误响应是 ProblemDetails
[Route("api/[controller]")]
public class MyController : ControllerBase { ... }

在这里插入图片描述

http://www.dtcms.com/a/263937.html

相关文章：

  • Qt/C++运行报错：exited with code -1073741819
  • scp (Secure Copy Protocol)指令集
  • 向量数据库全面解析：原理、功能与主流产品对比
  • 学习笔记（C++篇）—— Day 9
  • Terraform Helm：微服务基础设施即代码
  • Kubernetes Pod 调度基础
  • 飞算JavaAI：重构软件开发范式的智能引擎
  • 【SQL知识】PDO 和 MySQLi 的区别
  • python __doc__
  • gateway白名单存储nacos，改成存储数据库
  • leetcode124-二叉树中的最大路径和
  • CPU缓存一致性
  • AI智能体在用户行为数据分析中有哪些应用？
  • 具身多模态大模型在感知与交互方面的综述
  • （十一）Spring WebSocket
  • Ansys Speos | Speos Camera 传感器机器视觉示例
  • vue-35（使用 Jest 和 Vue Test Utils 设置测试环境）
  • 列表元素滚动动画
  • LAN8720 寄存器概览和STM32 HAL库读写测试
  • CSS 安装使用教程
  • FreeRTOS任务切换
  • 力扣网C语言编程题：寻找两个正序数组的中位数
  • RIP 技术深度解析
  • 文心一言开源版测评：能力、易用性与价值的全面解析
  • [创业之路-457]：企业经营层 - 蓝海战略 - 价值创新不仅仅是技术创新
  • Java项目：基于SSM框架实现的智慧养老平台管理系统【ssm+B/S架构+源码+数据库+毕业论文】
  • 大麦基于HarmonyOS星盾安全架构，打造全链路安全抢票方案
  • 【机器学习深度学习】模型微调的基本概念与流程
  • 06会话管理
  • 前端计算机视觉：使用 OpenCV.js 在浏览器中实现图像处理