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

优质文章学习记录

— 11 min read
在这里插入图片描述

文章目录

在这里插入图片描述

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

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

  • [ApiController]
    • 作用： 应用于控制器类。启用 API 特定的约定和行为：
      • 自动 HTTP 400 响应： 当模型验证失败时，自动返回 BadRequestResult (400)，包含 ModelState 错误详情。
      • 推断参数源： 自动推断复杂类型参数来自请求体 ([FromBody])，简单类型来自查询字符串 ([FromQuery]) 或路由 ([FromRoute])。
      • 属性路由要求： 要求控制器使用 [Route] 或 [HttpGet] 等属性定义路由。
      • 错误状态码详细信息： 在 4xx 错误响应中包含 ProblemDetails 格式的错误信息。
  • [Route]
    • 作用： 定义控制器或 Action 方法的 URL 路由模板。可应用于控制器（为所有 Action 方法设置前缀）或 Action 方法。
    • 参数：
      • Template (必填): URL 路由模板字符串。可以使用 [controller]（控制器名去掉 “Controller” 后缀）、[action]（方法名）占位符。模板中可用 {param} 定义路由参数。
      • Name (可选): 为路由指定一个唯一名称，用于生成 URL (IUrlHelper 或链接)。
      • Order (可选): 路由匹配的顺序（数字越小优先级越高）。
  • HTTP 方法属性 ([HttpGet], [HttpPost], [HttpPut], [HttpDelete], [HttpPatch], [HttpHead], [HttpOptions])
    • 作用： 指定 Action 方法响应哪个 HTTP 方法（动词）。它们本质上是带有固定 HttpMethod 的 [HttpMethod] 属性的快捷方式。通常与 [Route] 或内联路由模板一起使用。
    • 参数：
      • Template (可选): 内联的路由模板字符串。如果提供，它会覆盖或附加到控制器路由模板。
      • Name (可选): 路由名称。
      • Order (可选): 路由顺序。
  • [AcceptVerbs]
    • 作用： 允许 Action 方法响应多个 HTTP 方法。指定一个或多个 HTTP 方法字符串（如 "GET", "POST", "PATCH"）。
    • 参数：
      • verbs (必填): 允许的 HTTP 方法列表。
  • [NonAction]
    • 作用： 标记控制器类中的某个公共方法不是一个 Action 方法。防止 MVC 框架将其视为可路由的 HTTP 端点。

示例：

publicclassUsersController:ControllerBase{// 这是一个 Action 方法[HttpGet("{id}")]publicIActionResultGetUser(int id){...}// 这是一个公共辅助方法，但不是 Action[NonAction]publicstringGeneratePasswordResetToken(){...}}

示例：

[AcceptVerbs("GET","HEAD")]// 响应 GET 和 HEAD 请求publicIActionResultGetInfo(int id){...}

示例：

[HttpGet]// 映射到 GET api/productspublicIEnumerable<Product>GetAll(){...}[HttpGet("{id}")]// 映射到 GET api/products/5publicActionResult<Product>GetById(int id){...}[HttpPost("create")]// 映射到 POST api/products/createpublicIActionResultCreateProduct([FromBody]Product product){...}[HttpPut("{id}")]// 映射到 PUT api/products/5publicIActionResultUpdateProduct(int id,[FromBody]Product product){...}[HttpDelete("{id}")]// 映射到 DELETE api/products/5publicIActionResultDeleteProduct(int id){...}

示例：

[ApiController][Route("api/v{version:apiVersion}/[controller]")]// 控制器级路由，带版本publicclassOrdersController:ControllerBase{[HttpGet("{id:int}")]// Action 级路由，组合成 api/v1/orders/5publicIActionResultGetById(int id){...}[HttpPost]// 使用控制器路由前缀：api/v1/orderspublicIActionResultCreate(Order order){...}[Route("~/legacy/orders")]// 覆盖控制器前缀，使用根级路由 /legacy/orderspublicIActionResultGetLegacyOrders(){...}}

示例：

[ApiController][Route("api/[controller]")]// 必需属性路由publicclassProductsController:ControllerBase{// ...}

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

  • [FromBody]
    • 作用： 指示参数应从 HTTP 请求的正文中绑定。通常用于绑定复杂的 JSON/XML 对象。在 [ApiController] 中，复杂类型参数默认使用此来源。
  • [FromQuery]
    • 作用： 指示参数应从 URL 查询字符串中绑定。在 [ApiController] 中，简单类型参数默认使用此来源。
  • [FromRoute]
    • 作用： 指示参数应从 URL 路由数据中绑定（由路由模板中的 {param} 定义）。在 [ApiController] 中，如果路由模板中有匹配名称的参数，默认使用此来源。
  • [FromHeader]
    • 作用： 指示参数应从 HTTP 请求头中绑定。
  • [FromForm]
    • 作用： 指示参数应从 HTTP 请求的已提交表单数据中绑定。常用于 multipart/form-data 或 application/x-www-form-urlencoded 内容类型。
  • [FromServices]
    • 作用： 指示参数应通过依赖注入 (DI) 容器解析获得，而不是从请求中绑定。用于在 Action 方法中注入服务。
  • [BindRequired] / [BindNever]
    • 作用：
      • [BindRequired]: 指示参数是必需的，如果无法绑定（如从查询字符串缺少值），则模型验证会失败。
      • [BindNever]: 指示参数应被完全忽略，不进行绑定。常用于防止过度提交攻击（Mass Assignment）。

示例：

publicclassUserUpdateModel{publicstring Username {get;set;}[BindRequired]// 更新时必须提供 Emailpublicstring Email {get;set;}[BindNever]// 防止客户端设置 IsAdmin 属性publicbool IsAdmin {get;set;}}

示例：

[HttpPost]publicIActionResultPlaceOrder(Order order,[FromServices]IOrderService orderService){ orderService.ProcessOrder(order);returnOk();}

示例：

[HttpPost("upload")]publicIActionResultUploadFile([FromForm]IFormFile file,[FromForm]string description){// ...}

示例：

[HttpGet]publicIActionResultGet([FromHeader(Name ="X-Client-Version")]string clientVersion){// 从请求头 X-Client-Version 获取值}

示例：

[HttpGet("{id:int}")]publicIActionResultGetById([FromRoute]int id)// 从路由 /api/products/5 中绑定 id=5{// ...}

示例：

[HttpGet("search")]publicIActionResultSearchProducts([FromQuery]string name,[FromQuery]int? minPrice){// GET /api/products/search?name=apple&minPrice=10}

示例：

[HttpPost]publicIActionResultCreate([FromBody]Product product)// 从请求体 JSON 绑定{// ...}

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

  • [Produces]
    • 作用： 应用于控制器或 Action 方法，指定 Action 方法返回的响应内容类型（MIME 类型，如 "application/json", "application/xml"）。影响 Content-Type 响应头和客户端内容协商。
    • 参数：
      • contentType (必填): 内容类型字符串。
      • Type (可选): 返回对象类型的 Type (常用于 Swagger 文档)。
      • StatusCodes (可选): 关联的状态码数组 (常用于 Swagger 文档)。
  • [Consumes]
    • 作用： 应用于控制器或 Action 方法，指定 Action 方法接受的请求内容类型（MIME 类型）。用于内容协商，如果请求的 Content-Type 不匹配，框架会返回 415 Unsupported Media Type。
    • 参数：
      • contentType (必填): 内容类型字符串。
  • [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 (可选): 响应的内容类型。
  • [ProducesDefaultResponseType]
    • 作用： 当无法匹配其他 [ProducesResponseType] 指定的状态码时，指定一个默认的响应类型。常用于捕获未明确声明的错误（如 500 Internal Server Error）。
    • 参数：
      • Type (可选): 默认响应的对象类型（通常是 ProblemDetails）。

示例：

[HttpDelete("{id}")][ProducesResponseType(StatusCodes.Status204NoContent)]// 删除成功[ProducesResponseType(StatusCodes.Status404NotFound)]// 找不到资源[ProducesDefaultResponseType(typeof(ProblemDetails))]// 其他错误（如服务器异常）publicIActionResultDelete(int id){try{// ... 删除逻辑，可能抛出异常returnNoContent();}catch(NotFoundException){returnNotFound();}// 其他异常会被 [ApiController] 捕获并返回 500 + ProblemDetails}

示例：

[HttpGet("{id}")][ProducesResponseType(StatusCodes.Status200OK, Type =typeof(Product))]// 成功返回 Product[ProducesResponseType(StatusCodes.Status404NotFound)]// 找不到资源[ProducesResponseType(StatusCodes.Status400BadRequest)]// 无效请求（如 id 格式错误）publicActionResult<Product>GetById(int id){if(id <=0)returnBadRequest("ID must be positive");var product = _repository.GetProduct(id);if(product ==null)returnNotFound();return product;}[HttpPost][ProducesResponseType(StatusCodes.Status201Created, Type =typeof(Product))]// 创建成功，返回新资源[ProducesResponseType(StatusCodes.Status400BadRequest, Type =typeof(ValidationProblemDetails))]// 验证失败，返回 ProblemDetailspublicasyncTask<ActionResult<Product>>Create([FromBody]Product product){if(!ModelState.IsValid)returnBadRequest(ModelState);// [ApiController] 自动处理为 400 + ValidationProblemDetailsvar createdProduct =await _repository.AddProductAsync(product);returnCreatedAtAction(nameof(GetById),new{ id = createdProduct.Id }, createdProduct);// 201 Created}

示例：

[HttpPost][Consumes("application/json")]// 只接受 Content-Type 为 application/json 的请求publicIActionResultCreate([FromBody]Product product){...}[HttpPost("upload")][Consumes("multipart/form-data")]// 接受文件上传publicIActionResultUpload([FromForm]IFormFile file){...}

示例：

[ApiController][Route("api/[controller]")][Produces("application/json")]// 控制器级：所有 Action 默认生成 JSONpublicclassProductsController:ControllerBase{[HttpGet("{id}")][Produces("application/xml")]// 覆盖控制器设置，此 Action 生成 XMLpublicProductGetById(int id){...}[HttpGet][Produces("application/json","application/xml")]// 支持 JSON 和 XML 内容协商publicIEnumerable<Product>GetAll(){...}}

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

  • [Authorize]
    • 作用： 要求用户必须经过认证（登录）才能访问该控制器或 Action 方法。如果未认证，返回 401 Unauthorized。可应用于控制器（保护所有方法）或单个 Action 方法。
    • 参数：
      • AuthenticationSchemes (可选): 指定使用的认证方案（如 "Bearer", "Cookies"）。
      • Policy (可选): 指定授权策略名称（需要在 Startup.cs 中配置策略）。
      • Roles (可选): 指定允许访问的用户角色（逗号分隔）。用户需要拥有其中至少一个角色。
  • [AllowAnonymous]
    • 作用： 允许匿名用户访问被 [Authorize] 保护的控制器或 Action 方法。通常用于登录、注册等不需要认证的接口。
    • 示例： 见上面 [Authorize] 示例中的 PublicInfo 方法。
  • [Authorize(Policy = "...")]
    • 作用： 使用自定义授权策略进行访问控制。策略在 Startup.cs 的 ConfigureServices 中使用 services.AddAuthorization 配置，可以包含复杂的授权要求（如年龄限制、声明要求、自定义处理程序）。
  • [RequiredScope] (通常用于 Azure AD / Microsoft Identity Platform)
    • 作用： 要求请求的访问令牌 (access_token) 必须包含指定的作用域 (Scope)。这是实现 OAuth2 权限控制的关键。
    • 参数：
      • RequiredScopes (必填): 要求的作用域数组。

示例：

[HttpGet("reports")][RequiredScope("Reports.Read","Reports.ReadWrite")]// 需要 Reports.Read 或 Reports.ReadWrite 权限publicIActionResultGetReports(){...}

示例：

// 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])publicIActionResultDelete(int id){...}

示例：

[ApiController][Authorize]// 整个控制器需要登录[Route("api/[controller]")]publicclassSecureController:ControllerBase{[HttpGet("userinfo")]publicIActionResultGetUserInfo(){...}// 需要登录[HttpGet("admin")][Authorize(Roles ="Administrator")]// 需要登录且角色为 AdministratorpublicIActionResultAdminOnly(){...}}[AllowAnonymous]// 覆盖控制器的 [Authorize]，允许匿名访问[HttpGet("public")]publicIActionResultPublicInfo(){...}

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

  • [SwaggerOperation] (Swashbuckle)
    • 作用： 为特定的 API 操作（Action 方法）添加摘要 (Summary) 和详细描述 (Description)。
    • 参数：
      • Summary: 操作的简短摘要。
      • Description: 操作的详细描述。
      • OperationId: 自定义操作的唯一标识符（覆盖默认生成）。
      • Tags: 自定义操作的标签（覆盖默认的控制器名）。
  • [SwaggerResponse] (Swashbuckle)
    • 作用： 替代或补充 [ProducesResponseType]，为 Swagger 提供更详细的响应信息（如响应头、示例）。与 [ProducesResponseType] 通常一起使用或单独使用。
    • 参数：
      • statusCode (必填): HTTP 状态码。
      • Type (可选): 响应体类型。
      • Description (可选): 响应的描述。
      • ContentTypes (可选): 响应的内容类型。
  • [SwaggerParameter] (Swashbuckle)
    • 作用： 为参数添加描述或指定其是否必需（覆盖默认推断）。
    • 参数：
      • Name: 参数名称。
      • Description: 参数描述。
      • Required: 是否必需（覆盖默认）。
      • In: 参数位置 (ParameterLocation.Query, .Path, .Header, .Body)，覆盖默认推断。
  • [SwaggerSchema] (Swashbuckle)
    • 作用： 应用于模型类或属性，为 Swagger Schema 提供额外信息（如描述、示例值、是否只读/必填）。
    • 参数：
      • Description: 模型或属性的描述。
      • ReadOnly: 是否只读（在响应中出现，不应在请求中发送）。
      • Required: 是否必需（覆盖数据注解的 [Required] 对于 Swagger 的影响）。
      • Example: 提供示例值。
  • [ProducesErrorResponseType] (AspNetCore.Mvc) - 与 Swagger 配合
    • 作用： 当与 [ProducesDefaultResponseType] 或特定错误 [ProducesResponseType] 结合使用时，明确告知 Swagger 默认错误响应的类型（通常是 ProblemDetails 或 HttpValidationProblemDetails）。

示例：

[ApiController][ProducesErrorResponseType(typeof(ProblemDetails))]// 告诉 Swagger 默认错误响应是 ProblemDetails[Route("api/[controller]")]publicclassMyController:ControllerBase{...}

示例：

publicclassProduct{[SwaggerSchema("The unique identifier of the product", ReadOnly =true)]publicint Id {get;set;}[Required][SwaggerSchema("The name of the product", Example ="Apple iPhone 13")]publicstring Name {get;set;}[SwaggerSchema("The price in USD", Format ="decimal")]publicdecimal Price {get;set;}}

示例：

[HttpGet("search")]publicIActionResultSearch([FromQuery,SwaggerParameter("Name of the product to search for", Required =true)]string name,[FromQuery,SwaggerParameter("Minimum price filter")]decimal? minPrice){...}

示例：

[HttpGet("{id}")][ProducesResponseType(StatusCodes.Status200OK)]// MVC 行为[SwaggerResponse(200,"The product was found",typeof(Product))]// Swagger 文档增强[SwaggerResponse(404,"The product does not exist",typeof(NotFoundResult))]publicActionResult<Product>GetById(int id){...}

示例：

[HttpPost][SwaggerOperation( Summary ="Creates a new product", Description ="Requires administrator privileges. Returns the created product with its generated ID.", OperationId ="CreateProduct", Tags =new[]{"Admin"})]publicActionResult<Product>Create([FromBody]Product product){...}
在这里插入图片描述

Read more

Kubernetes 与 AI 集成最佳实践

Kubernetes 与 AI 集成最佳实践 一、前言 哥们，别整那些花里胡哨的。Kubernetes 与 AI 集成是现代云原生架构的重要趋势，今天直接上硬货，教你如何在 Kubernetes 中部署和管理 AI 工作负载。 二、AI 工作负载类型 类型特点资源需求训练工作负载计算密集型高 GPU 需求推理工作负载低延迟要求中等 GPU 需求数据处理存储密集型高存储 I/O模型服务高并发稳定资源需求 三、实战配置 1. GPU 资源管理 apiVersion: v1 kind: ConfigMap metadata: name: nvidia-device-plugin namespace: kube-system data: config.yaml: | version: v1 flags: migStrategy: single
Flutter 组件 tavily_dart 的适配 鸿蒙Harmony 深度进阶 - 驾驭 AI 原生聚合搜索、实现鸿蒙端跨域知识发现与垂直领域语义降噪方案

Flutter 组件 tavily_dart 的适配 鸿蒙Harmony 深度进阶 - 驾驭 AI 原生聚合搜索、实现鸿蒙端跨域知识发现与垂直领域语义降噪方案

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.ZEEKLOG.net Flutter 组件 tavily_dart 的适配 鸿蒙Harmony 深度进阶 - 驾驭 AI 原生聚合搜索、实现鸿蒙端跨域知识发现与垂直领域语义降噪方案 前言 在前文中，我们领略了 tavily_dart 在鸿蒙（OpenHarmony）生态中实现基础互联网 AI 搜索集成的魅力。但在真正的“跨国科研智能辅助”、“政务决策舆情态势感知”以及“需要接入高精密专业数据库”的场景中。简单的单次查询往往不足以触达知识的核心。面对需要在大规模并发环境下，针对特定行业域名（如 .gov / .edu）执行深层内容的并行嗅探，并且要求对回显的数万字内容执行基于 AI 强语义的重排序（Re-ranking）与引用链路审计的高阶需求。如果缺乏一套完善的聚合搜索策略与语义降噪模型。不仅会导致 AI 智能体出现由于“信息泛滥”
OpenClaw接入企业微信全攻略：从0到1打通企业AI协作通道

OpenClaw接入企业微信全攻略：从0到1打通企业AI协作通道

摘要：本文详细介绍了将OpenClaw AI框架接入企业微信的完整方案。通过两种主流接入方式（API模式机器人和自建应用），企业可以快速实现智能问答、流程自动化等AI能力落地。文章重点讲解了从前期准备、核心接入流程到生产环境部署的全套实操步骤，包括权限配置、网络设置、参数对接等关键环节。同时提供了进阶优化建议，如后台守护、HTTPS加固、权限管控等企业级功能配置，以及常见问题排查方法。该方案能有效解决企业信息孤岛问题，将AI能力无缝嵌入员工日常办公场景，在保障数据安全的同时显著提升工作效率。 目录 一、前言：为什么要将OpenClaw接入企业微信？ 二、接入前置准备 OpenClaw介绍 接入准备工作 三、核心接入流程（两种方案任选） 方案一：API模式机器人接入（新手首选，快速上手） 步骤1：企业微信后台创建API模式机器人 步骤2：OpenClaw安装企微插件并配置参数 步骤3：完成机器人创建并测试联调 方案二：企业微信自建应用接入（企业级进阶方案） 步骤1：企业微信创建自建应用并获取核心凭证 步骤2：OpenClaw配置自建应用核心参数 步骤3：启用应

Midjourney Imagine API 申请及使用

Midjourney Imagine API 申请及使用 Midjourney 是一款非常强大的 AI 绘图工具，只要输入关键字，就能在短短一两分钟生成十分精美的图像。Midjourney 以其出色的绘图能力在业界独树一帜，如今，Midjourney 早已在各个行业和领域广泛应用，其影响力愈发显著。 本文档主要介绍 Midjourney API 中 Imagine 操作的使用流程，利用它我们可以轻松通过文本生成所需要的图像。 申请流程 要使用 Midjourney Imagine API，首先可以到 Midjourney Imagine API 页面点击「Acquire」按钮，获取请求所需要的凭证： 如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。 在首次申请时会有免费额度赠送，可以免费使用该 API。 基本使用 接下来就可以在界面上填写对应的内容，如图所示： 在第一次使用该接口时，我们至少需要填写两个内容，一个是 authorization，直接在下拉列表里面选择即可。