筆記目錄

雲翼的技術隨筆

主題

註：此版本由 AI 自動翻譯與摘要，不保證內容絕對精確
原始筆記

ASP.NET Core Web API 入門心得 ​

TLDR ​

  • ControllerBase 適合純 Web API 開發，若需 View 支援或 Filter 事件則繼承 Controller。
  • [ApiController] 提供屬性路由、HTTP 400 自動回應、參數繫結推斷等自動化行為。
  • 建議使用 ActionResult<T> 作為 Action 回傳型別，以兼顧資料回傳與狀態碼控制。
  • 路由設定建議使用 [Route] Attribute，並明確標示 [HttpGet]、[HttpPost] 等動詞。
  • Swagger 整合時，務必為每個 Action 加上 HTTP Attribute，否則可能導致 UI 顯示異常。
  • 可透過 IOperationFilter 在 Swagger 中加入自訂欄位（如 Token）。
  • 啟用 XML 文件註解可大幅提升 Swagger 文件品質，需在 .csproj 設定 GenerateDocumentationFile。

建立專案與基礎設定 ​

在 Visual Studio 建立 Web API 專案時，建議注意以下幾點：

  • 啟用 OpenAPI 支援：勾選後會自動安裝 Swashbuckle.AspNetCore 並配置 Swagger。
  • 最上層陳述式 (Top-level statements)：C# 9.0 功能，簡化 Program.cs 結構，移除傳統 Program 類別與 Main 方法。
  • 使用控制器：若不勾選則會建立「最小 API (Minimal APIs)」，適合輕量化服務。

Controller 與 ApiController 說明 ​

ControllerBase 與 Controller 的差異 ​

什麼情況下會遇到這個問題：當你需要決定 Controller 的繼承基礎時。

  • ControllerBase：Web API 的預設基礎類別，不包含 View 相關功能。
  • Controller：繼承自 ControllerBase，額外提供 View 支援及 OnActionExecuting 等 Filter 事件。若需同時支援 View 與 API，建議繼承此類別。

ApiController 的行為 ​

什麼情況下會遇到這個問題：當你希望簡化 API 的驗證與參數繫結邏輯時。 標記 [ApiController] 後，系統會自動啟用以下功能：

  • 屬性路由需求。
  • HTTP 400 自動回應（自動檢查 ModelState）。
  • 繫結來源參數推斷（如 [FromBody]、[FromQuery] 等）。
  • 多部分/表單資料要求推斷。
  • 錯誤狀態碼的問題詳細資料。

若需停用部分行為，可在 Program.cs 的 AddControllers() 中透過 ConfigureApiBehaviorOptions 進行調整。

路由與參數繫結 ​

屬性路由 (Attribute Routing) ​

什麼情況下會遇到這個問題：當你需要定義 RESTful 風格或自訂 API 路徑時。 ASP.NET Core 採用 [Route] Attribute 進行路由設定。優先權由高至低為：Action > Controller > 父類別。

TIP

  • 設定 [ApiController] 後，慣例路由（如 UseEndpoints 定義的路由）將失效。
  • 路由參數使用中括號 []（如 [controller]），而非慣例路由的大括號 {}。

參數繫結推斷 ​

什麼情況下會遇到這個問題：當你需要明確指定參數來源時。 系統會根據型別自動推斷來源：

  • [FromBody]：複雜型別。
  • [FromForm]：IFormFile 或 IFormFileCollection。
  • [FromRoute]：符合路由範本的參數。
  • [FromQuery]：其他參數。

回傳型別建議 ​

什麼情況下會遇到這個問題：當你需要規範 API 的回傳格式時。 建議優先使用 ActionResult<T>，它允許開發者同時回傳資料與 HTTP 狀態碼，且在 Swagger 文件中能正確顯示回傳型別。

csharp
[HttpGet("{id}")]
public ActionResult<string> GetById(int? id) {
    if (!id.HasValue) {
        return BadRequest("Invalid id");
    }
    return $"GET method with id {id}";
}

Swagger 整合與最佳實踐 ​

確保 Swagger 正常運作 ​

什麼情況下會遇到這個問題：當你的 API 在 Swagger UI 中無法正確顯示或測試時。 注意：即使未明確設定 HTTP Attribute，API 預設為 GET 請求。但為了確保 Swagger 能正確解析並顯示描述，請務必為每個 Action 明確標示 [HttpGet]、[HttpPost] 等 Attribute，並避免設計非 Action 的 public 方法。

整合 XML 註解 ​

什麼情況下會遇到這個問題：當你需要讓 API 文件包含詳細的參數說明與範例時。

  1. 在 .csproj 加入以下設定：
xml
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
  1. 在 Program.cs 的 AddSwaggerGen 中加入 XML 路徑設定：
csharp
builder.Services.AddSwaggerGen(opt => {
    string xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    opt.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

擴充 Swagger 功能 ​

什麼情況下會遇到這個問題：當你需要加入全域參數（如 Token）時。 可實作 IOperationFilter 介面並在 AddSwaggerGen 中註冊，即可在所有 API 介面中加入自訂輸入欄位。

異動歷程 ​

  • 2023-08-04 初版文件建立。