IActionResult（接口）
    └── ActionResult（抽象類，默認(rèn)實(shí)現(xiàn)）
            ├── StatusCodeResult
            │       ├── NotFoundResult (404)
            │       ├── OkResult (200)
            │       └── BadRequestResult (400) ...
            ├── ObjectResult（帶 Body，最復(fù)雜）
            │       ├── OkObjectResult (200)
            │       ├── NotFoundObjectResult (404)
            │       ├── BadRequestObjectResult (400)
            │       ├── CreatedResult (201)
            │       └── CreatedAtActionResult (201) ...
            ├── ContentResult
            ├── JsonResult
            ├── FileResult
            ├── RedirectResult
            └── ViewResult ...

// 命名空間: Microsoft.AspNetCore.Mvc
public interface IActionResult
{
    // 由 MVC 框架調(diào)用，用于處理 Action 方法的返回結(jié)果
    Task ExecuteResultAsync(ActionContext context);
}

public class ActionContext
{
    public HttpContext          HttpContext       { get; }  // 整個(gè) HTTP 請(qǐng)求/響應(yīng)
    public RouteData            RouteData         { get; }  // 路由數(shù)據(jù)
    public ActionDescriptor     ActionDescriptor  { get; }  // Action 的元數(shù)據(jù)
    public ModelStateDictionary ModelState        { get; }  // 模型驗(yàn)證狀態(tài)
}

public abstract class ActionResult : IActionResult
{
    // 同步版本（供簡(jiǎn)單場(chǎng)景使用，子類可選擇重寫）
    public virtual void ExecuteResult(ActionContext context) { }
    // 異步版本：默認(rèn)實(shí)現(xiàn)調(diào)用同步方法，再返回 Task.CompletedTask
    // 需要真正異步 I/O 的子類（如寫文件流）應(yīng)直接重寫此方法
    public virtual Task ExecuteResultAsync(ActionContext context)
    {
        ExecuteResult(context);
        return Task.CompletedTask;
    }
}

public class StatusCodeResult : ActionResult, IStatusCodeActionResult
{
    public int StatusCode { get; }
    public StatusCodeResult(int statusCode) { StatusCode = statusCode; }
    // 重寫同步方法，邏輯極簡(jiǎn)：只設(shè)置狀態(tài)碼
    public override void ExecuteResult(ActionContext context)
    {
        context.HttpContext.Response.StatusCode = StatusCode;
    }
}
// 子類只做一件事：傳入固定的狀態(tài)碼
public class NotFoundResult : StatusCodeResult
{
    public NotFoundResult() : base(StatusCodes.Status404NotFound) { }
}
public class OkResult : StatusCodeResult
{
    public OkResult() : base(StatusCodes.Status200OK) { }
}

public class ObjectResult : ActionResult, IStatusCodeActionResult
{
    public object?   Value        { get; set; }  // 要序列化的對(duì)象
    public int?      StatusCode   { get; set; }  // HTTP 狀態(tài)碼（可空）
    public MediaTypeCollection ContentTypes { get; set; }
    public FormatterCollection<IOutputFormatter> Formatters { get; set; }
    // 重寫異步版本（序列化寫流是 I/O 操作）
    public override async Task ExecuteResultAsync(ActionContext context)
    {
        // 子類在序列化前可修改狀態(tài)（如設(shè)置 StatusCode、寫 Header）
        OnFormatting(context);
        // 委托給 ObjectResultExecutor，它負(fù)責(zé)：
        // 1. 內(nèi)容協(xié)商：根據(jù) Accept 頭選擇 Formatter
        // 2. 調(diào)用 IOutputFormatter 序列化 Value
        // 3. 設(shè)置 Content-Type 和 StatusCode
        var executor = context.HttpContext.RequestServices
            .GetRequiredService<IActionResultExecutor<ObjectResult>>();
        await executor.ExecuteAsync(context, this);
    }
    public virtual void OnFormatting(ActionContext context) { }
}

public class OkObjectResult : ObjectResult
{
    public OkObjectResult(object? value) : base(value)
    { StatusCode = StatusCodes.Status200OK; }
}
// CreatedAtActionResult 更特殊：重寫了 OnFormatting 來(lái)設(shè)置 Location Header
public class CreatedAtActionResult : ObjectResult
{
    public string? ActionName     { get; set; }
    public string? ControllerName { get; set; }
    public object? RouteValues    { get; set; }
    public override void OnFormatting(ActionContext context)
    {
        var url = urlHelper.Action(ActionName, ControllerName, RouteValues);
        context.HttpContext.Response.Headers[HeaderNames.Location] = url;
    }
}

[HttpGet]
public Task<List<Product>> Get() =>
    _db.Products.OrderBy(p => p.Name).ToListAsync();

[HttpGet("{id}")]
[ProducesResponseType<Product>(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public IActionResult GetById(int id)
{
    var product = _db.Products.Find(id);
    return product == null ? NotFound() : Ok(product);
}

[HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public ActionResult<Product> GetById(int id)
{
    var product = _db.Products.Find(id);
    // 直接 return product，隱式轉(zhuǎn)換自動(dòng)包裝成 OkObjectResult
    return product == null ? NotFound() : product;
}

[HttpGet("{id}")]
public Results<NotFound, Ok<Product>> GetById(int id)
{
    var product = _db.Products.Find(id);
    return product == null
        ? TypedResults.NotFound()
        : TypedResults.Ok(product);
    // 返回其他類型 → 編譯錯(cuò)誤！
}

HTTP 請(qǐng)求
    │
    ▼
中間件管道（UseRouting → UseAuthentication → UseEndpoints）
    │
    ▼
ControllerActionInvoker（核心調(diào)度器）
    │
    ├─── [1] Authorization Filter ──────────── OnAuthorizationAsync
    │          不通過(guò) → 直接短路，寫入 401/403
    │
    ├─── [2] Resource Filter ────────────────── OnResourceExecutingAsync
    │          可短路（如緩存命中直接返回）
    │
    ├─── [3] Model Binding
    │          綁定 Action 參數(shù)；[ApiController] 時(shí)驗(yàn)證失敗自動(dòng)返回 400
    │
    ├─── [4] Action Filter Before ───────────── OnActionExecutingAsync
    │          可修改參數(shù)，或設(shè)置 context.Result 短路
    │
    ├─── ★★★ [5] 執(zhí)行 Action 方法本體 ★★★
    │          return Ok(product)
    │          → 創(chuàng)建 OkObjectResult 對(duì)象，此時(shí)【尚未寫入任何響應(yīng)】
    │
    ├─── [6] Action Filter After ────────────── OnActionExecutedAsync
    │          可攔截并替換 context.Result
    │
    ├─── [7] Exception Filter
    │          處理未被捕獲的異常
    │
    ├─── [8] Result Filter Before ───────────── OnResultExecutingAsync
    │          寫響應(yīng)前最后處理（如追加響應(yīng) Header）
    │
    ├─── ★★★ [9] result.ExecuteResultAsync(actionContext) ★★★
    │          真正把狀態(tài)碼、Header、Body 寫入 HttpResponse
    │
    └─── [10] Result Filter After + Resource Filter After
               OnResultExecutedAsync / OnResourceExecutedAsync
    │
    ▼
HTTP 響應(yīng)返回客戶端

public IActionResult GetById(int id)
{
    var product = _db.Products.Find(id);
    return product == null ? NotFound() : Ok(product);
}

[步驟 1] ControllerBase.Ok(product)
         → new OkObjectResult(product)
            StatusCode = 200, Value = product 對(duì)象（內(nèi)存中的 C# 對(duì)象）
[步驟 2] Action 方法返回，ControllerActionInvoker 拿到 OkObjectResult
         經(jīng)過(guò) Action Filter (OnActionExecuted)
         經(jīng)過(guò) Result Filter (OnResultExecuting)
[步驟 3] 框架調(diào)用：
         await result.ExecuteResultAsync(actionContext)
[步驟 4] ObjectResult.ExecuteResultAsync 內(nèi)部：
         OnFormatting(context)    // OkObjectResult 確認(rèn) StatusCode = 200
         var executor = services.GetRequiredService<IActionResultExecutor<ObjectResult>>()
         await executor.ExecuteAsync(context, this)
[步驟 5] ObjectResultExecutor.ExecuteAsync 內(nèi)部：
         a. 內(nèi)容協(xié)商：檢查請(qǐng)求 Accept 頭（application/json? application/xml?）
         b. 從 IOutputFormatter 列表中選擇匹配的 Formatter
            → 默認(rèn)是 SystemTextJsonOutputFormatter
         c. Response.StatusCode = 200
         d. Response.ContentType = "application/json; charset=utf-8"
         e. formatter.WriteAsync(context)
            → 將 product 序列化為 JSON，寫入 Response.Body 流

// MVC 體系（Microsoft.AspNetCore.Mvc）
public interface IActionResult
{
    Task ExecuteResultAsync(ActionContext context);  // 參數(shù)是 ActionContext
}
// Minimal API 體系（Microsoft.AspNetCore.Http）
public interface IResult
{
    Task ExecuteAsync(HttpContext httpContext);       // 參數(shù)是 HttpContext，更輕量
}

// Microsoft.AspNetCore.Http.HttpResults.Ok<TValue>
public sealed class Ok<TValue> : IResult, IStatusCodeHttpResult
{
    public int?    StatusCode => 200;
    public TValue? Value { get; }
    // 沒(méi)有 Formatter，沒(méi)有內(nèi)容協(xié)商，直接寫流
    public async Task ExecuteAsync(HttpContext httpContext)
    {
        httpContext.Response.StatusCode = 200;
        if (Value is not null)
            await httpContext.Response.WriteAsJsonAsync(Value);
    }
}

需要返回多種 HTTP 狀態(tài)？
├── 否 ──→ 直接返回具體類型（最簡(jiǎn)單）
└── 是
    │
    ├── 需要內(nèi)容協(xié)商或自定義 Formatter？
    │       └── 是 ──→ ActionResult<T>（MVC 場(chǎng)景首選）
    │
    └── 需要和 Minimal API 共享代碼？
            ├── 是 ──→ Results<T1, T2>（編譯期類型安全，自動(dòng)推斷文檔）
            └── 否 ──→ ActionResult<T>（現(xiàn)代 .NET 推薦寫法）