using .NET 10 中的最小 API 資料驗證：與 Tim Corey 深入探索

Minimal API 驗證介紹

Tim Corey 首先強調，在 .NET 10 中，Minimal APIs 應用了多次升級，其中請求驗證是其中的一個重要改進。 這使得透過查詢字串、標頭或請求正文的進入請求能夠自動被驗證。 Tim 強調，適當的驗證不僅改善開發者體驗，還可防止不良格式的請求達到業務邏輯，這對於維持資料完整性和保護敏感資訊至關重要。

Tim 也指出，他的影片是快速 10 分鐘訓練系列的一部分，旨在提供可行的指引而不深入抽象理論。 他鼓勵觀眾下載他的源程式碼以便跟進。

設置一個支援驗證的 Minimal API

為了演示驗證規則，Tim 從一個新項目中設置一個 minimal API，簡化以專注於 API 驗證。 他的範例 API 包括：

• 一個用於測試連接的 Hello World 端點。

• 一個接受 Person 物件的 POST 請求 /person 端點。

• 一個用於 Login 記錄的 POST 請求 /login 端點。

Tim 運行了 API 並顯示最初格式不正確的資料會被接受。 例如，傳送一個空白的 Person 物件或在 Login 記錄中傳送一個無效的電子郵件，但 API 回應仍然成功。 這展示了需要架構驗證和請求驗證，以防止無效資料在後端被處理。

將驗證服務新增至 Minimal APIs

Tim 解釋道，要實現正確的驗證，首先要在 API 中註冊驗證服務：

builder.Services.AddValidation();

加入此服務後，路由處理程式將自動對進入的請求執行型別檢查、格式驗證和內容驗證。 Tim 指出，此步驟至關重要，以確保驗證失敗產生錯誤資訊，而非讓惡意資料繞過系統。

驗證類別：以 Person 模型為例

Tim 使用 System.ComponentModel.DataAnnotations 新增驗證屬性至 Person 類別。 他將屬性標記為必需並實施具有最小長度限制的格式驗證：

[Required]
[MinLength(2)]
public string FirstName { get; set; }

[Required]
[MinLength(2)]
public string LastName { get; set; }

現在運行 API，若請求正文缺少必要欄位或包含格式不正確的資料將會引發驗證錯誤。 例如，傳送一個單字元的 LastName 會產生400 Bad Request 錯誤並伴隨詳細的錯誤資訊：

"The field LastName must be a string or array type with a minimum length of 2."

Tim 強調，使用這樣的驗證庫可減少程式碼重複，讓開發者可以專注於業務邏輯，而不需在每個路由處理程式中撰寫重複的驗證邏輯。

驗證記錄：以 Login 記錄為例

驗證記錄稍有不同，因為它們的屬性在構造函式中定義。 Tim 演示如何利用 [property:] 語法在記錄上強制執行驗證規則：

public record Login(
    [property: Required, EmailAddress] string Email,
    [property: Required, MinLength(10)] string Password,
    [property: Compare(nameof(Password))] string ConfirmPassword
);

Tim 解釋的關鍵點：

• 電子郵件驗證確保 Email 欄位符合正確的格式。

• 密碼的最小長度保護不良格式的請求或弱密碼。

• [Compare(nameof(Password))] 確保 ConfirmPassword 與原始 Password 匹配，以避免資料損壞或在巢狀物件中發生驗證失敗。

Tim 運行了 login 端點的 POST 請求，並顯示無效的電子郵件格式、短密碼或不匹配的確認密碼將自動觸發驗證錯誤。 一旦欄位符合預期格式，API 回應成功。

避免的陷阱：可存取性至關重要

Tim 指出一個微妙的陷阱：若類別或記錄不是公有的，驗證會悄無聲息地失敗。 即使 API 請求成功綁定到物件，驗證結果也不會被強制執行：

internal record Login(...); // 驗證將不會運行

他解釋道，儘管惡意資料或無效輸入仍可能填充物件，但驗證策略會被繞過。 此行為已在 ASP.NET Core 中有所記載，但 Visual Studio 並不會警告開發者，因此定期審視驗證規則並確保所有 API 模型為公有性至關重要。

使用 Minimal API 驗證的優勢

Tim 總結了在 Minimal APIs 中進行 API 資料驗證的優勢：

1. 消除手動驗證邏輯：無需為每個屬性撰寫重複的檢查。

2. 確保資料完整性：防止格式不正確的請求破壞後端或巢狀物件。

3. 提高安全性：減少暴露於惡意資料、SQL 注入、跨站指令碼攻擊及其他安全漏洞。

4. 提供清晰的錯誤訊息：回傳驗證失敗時，附有錯誤資訊及適當的 HTTP 狀態碼（如400 Bad Request）。

5. 提升開發者體驗：乾淨、聲明性驗證減少程式碼重複，並提高對 API 回應的信任。

6. 支持全面驗證：可自動工作於請求正文、查詢字串、標頭及巢狀物件上。

透過遵循 Tim 的方法，開發者可實現全面的驗證，而無需撰寫自定的驗證方法或在多個端點重複驗證邏輯。

結論

Tim Corey的影片提供了一個實用的、循序漸進的指南，用於在 .NET 10 的 Minimal APIs 中實施 API 驗證。從新增驗證服務到使用屬性裝飾類和記錄，並了解潛在的陷阱，Tim 展示如何有效地強制執行資料完整性、格式驗證和錯誤處理。

適當的 API 資料驗證保證您的 REST API 僅處理格式正確的請求，從而減少來自惡意資料、SQL 注入、跨站指令碼和其他安全漏洞的風險。 使用驗證規則、架構驗證和合適的驗證策略來增強開發者信任， 同時保持乾淨且安全的後端。

按 Tim的指導，開發者可實施穩健、安全及可靠的驗證管道，以確保每個 POST 請求、每個物件及每個 API 請求均遵循預期的格式，保護後端及最終使用者。