.NET core 之Controller编写

继承类

Web API 控制器通常应派生自 ControllerBase 而不是 Controller。

Controller 派生自 ControllerBase，并添加对视图的支持，因此它用于处理 Web 页面 ，而不是 Web API 请求。
如果同一控制器必须支持视图和 Web API，则派生自 Controller。

还有NotFound()、BadRequest()等方法可继承修改。

（长得像）注解/可用属性（不确定怎么叫的）
[Route]：指定Controller的 URL 模式。

异步方法

什么时候用？数据库访问等I/O时间长的操作，记得保持调用链全部异步！

    public async Task<ActionResult<WorkOrderResponse>> Create(
    [FromBody] CreateWorkOrderRequest request,
    CancellationToken cancellationToken)
    {
        var response = await workOrderService.CreateAsync(request, cancellationToken);
        return StatusCode(StatusCodes.Status201Created, response);
    }

• Task表示异步结果，async是异步方法修饰词。
• ActionResult允许返回 HTTP 响应，也能携带 WorkOrderResponse 数据。
• [FromBody] CreateWorkOrderRequest request：从 HTTP 请求体中读取 JSON，并绑定成 CreateWorkOrderRequest 对象。
• CancellationToken cancellationToken：接收请求取消信号。客户端断开连接或取消请求时，可以让后续操作尽早停止。
• StatusCode(StatusCodes.Status201Created, response)：构造一个HTTP 201响应（必要包装），并把 response 作为响应体。

async / await区别

• async: 定义异步方法时的修饰词，异步方法通常返回 Task 或 Task。

• await：
  用于等待一个异步操作完成，它只能在 async 方法中使用。
  使用 await 时，调用线程不会被阻塞，而是挂起当前方法的执行，待异步操作完成后自动恢复执行

同步方法

[ApiController]//标识一个类是专门处理 HTTP API 请求的控制器
[Route("api/[controller]")]// api/workorders
public sealed class WorkOrdersController(IWorkOrderService workOrderService) : ControllerBase
{
    //api/workorders/add; POST方法
    [HttpPost("add")]
    //ProducesResponseType用于 API 文档生成（如 Swagger/OpenAPI
    [ProducesResponseType(typeof(ApiResponse<>), StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    [ProducesResponseType(StatusCodes.Status403Forbidden)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public ApiResponse<WorkOrderResponse> AddWorkOrder([FromBody] CreateWorkOrderRequest request)
    {
        do something...
    }
}

• sealed：被 sealed 修饰的类不能被继承，而被 sealed 修饰的重写方法不能再被进一步重写。

参考链接

• https://learn.microsoft.com/zh-cn/aspnet/core/web-api/?view=aspnetcore-10.0