Minimal API 與程式啟動管線

從 WebApplicationBuilder 原始碼開始著手

核心概念

• WebApplication.CreateBuilder(args)：建立通用主機，載入設定、記錄、依賴注入容器與網頁主機預設組態
• builder.Build()：建立 WebApplication，同時具備主機與應用程式建構器功能，將註冊的中介軟體組裝為請求委派管線
• app.MapGet()/MapPost()：產生路由端點，執行時由端點路由中介軟體進行匹配，端點中介軟體執行對應委派並處理參數繫結與依賴注入
• app.Run()：啟動網頁伺服器，進入接收請求循環

啟動流程時序

1. CreateBuilder 階段

   • 建立主機與服務集合
   • 設定組態：appsettings.json、環境變數、使用者密鑰
   • 設定記錄：主控台、偵錯等輸出
   • 網頁主機預設：Kestrel、內容根目錄、IIS 整合

2. 服務與中介軟體註冊

   • 加入路由等基礎服務
   • 註冊 Swagger、資料庫內容、HTTP 用戶端、選項設定

3. Build 階段

   • 產生服務提供者
   • 建立應用程式建構器，注入內建中介軟體

4. 端點註冊

   • 透過 Map 方法建立路由端點，加入資料來源

5. 執行階段

   • 網頁伺服器綁定位址
   • 開始接受連線，請求進入中介軟體管線

關鍵元件職責

• WebApplicationBuilder：封裝主機構建器，提供服務、組態、記錄與網頁主機功能
• WebApplication：同時實作主機與應用程式建構器介面，持有中介軟體委派鏈與端點資料來源
• 應用程式建構器：收集中介軟體，最終組裝為請求委派
• 端點路由中介軟體：處理路由匹配與端點執行
• 端點資料來源：保存透過 Map 方法註冊的端點資訊

端點繫結與依賴注入流程

• 參數來源推斷順序：路由參數、查詢字串、標頭、請求本文、服務容器
• 支援簡單型別解析與自定義繫結
• 傳回型別處理：結果物件、自動序列化、非同步任務
• 例外處理：由開發或例外頁面中介軟體處理未捕捉例外

範例程式

var builder = WebApplication.CreateBuilder(args);

// 服務註冊
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.AddHttpClient("github");

// 應用程式建構與中介軟體設定
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
     app.UseSwagger();
     app.UseSwaggerUI();
}

app.UseHttpsRedirection();

// 端點定義
app.MapGet("/ping", () => Results.Ok(new { ok = true }));
app.MapGet("/repos/{owner}/{name}", async (string owner, string name, IHttpClientFactory factory) =>
{
     var http = factory.CreateClient("github");
     var url = $"https://api.github.com/repos/{owner}/{name}";
     var req = new HttpRequestMessage(HttpMethod.Get, url);
     req.Headers.UserAgent.ParseAdd("minimal-api");
     var resp = await http.SendAsync(req);
     return Results.Stream(await resp.Content.ReadAsStreamAsync(), "application/json");
});

app.Run();

管線組裝順序

• 典型順序：例外處理、HTTPS 重新導向、靜態檔案、路由、跨域與驗證、端點
• 內建路由與端點中介軟體，需注意中介軟體順序安排

組態與環境設定

• 環境變數控制監聽位址與執行環境
• 組態檔案自動載入與重新載入設定

注意事項

• 中介軟體順序影響功能有效性
• 請求本文重複讀取需啟用緩衝
• 依賴注入物件生命週期管理
• 非同步傳回值正確處理

原始碼參考路徑

• 預設建構器：WebApplicationBuilder 建構邏輯
• 主機專案：通用主機實作
• HTTP 抽象層：應用程式建構器與中介軟體基礎
• 路由專案：端點路由中介軟體實作
• 伺服器專案：網頁伺服器啟動與請求處理

進階應用

• 端點篩選器：實作橫切關注點
• 端點分組：共用中介軟體與路徑前綴
• 自訂結果物件：統一回應格式
• 啟動模式選擇：阻塞或非阻塞式啟動
• 健康狀態檢查：容器環境整合

以下是流程簡單的描述

狀態：已建立／等待啟動
　→ 呼叫 Start()／排程 → 等待執行
　　→ 執行緒池執行進入點 → 執行中
　　　→ 使用者委派執行：成功／拋出例外／拋出取消例外
　　　　→ 完成
　　　　　→ 若有附加子任務：等待子任務完成 → 最後子任務完成
　　　　　→ 第二階段完成：設定狀態為完成／錯誤／取消
　　　　　→ 第三階段完成：清理資源 ＋ 通知父任務 ＋ 執行接續動作
　　　　　　→ 啟動等待／接續任務／多重等待等後續操作