樣本 Web API 的簡介

Tim 一開始就解釋了創建新 Web API 專案對開發者的重大意義。 不管您是為移動裝置、網頁應用，還是其他軟體應用程式開發，擁有一個輕量的樣本 API 能讓測試更快更順暢。

Tim 說，到專案結束時，我們將擁有：

• 使用 ASP.NET Core 和 .NET Core 的最小 API，

• 支援 OpenAPI (Swagger UI) 的已文件化的 API，

• 健康檢查，

• 模擬錯誤和減速，

• 在 Docker 容器和 VPS 伺服器上的部署。

這個小型專案將使開發者能夠輕鬆地通過 HTTP 方法如 GET、PUT、POST 和 DELETE 與 HTTP 服務進行互動。

設置專案和樣本數據

Tim 開始在 Visual Studio -- 微軟的流行整合開發環境中構建 Web API 專案。

在1:07，Tim 建立了一個新的 Data 目錄並添加一個 courseData.json 文件。他提到他即時的網站 timcorey.com 使用了類似的系統——僅僅是一個在幕後作為 Web 服務運行的大 JSON 文件。

Tim 設置的關鍵要點：

• 使用 JSON 文件作為樣本數據，避免需要資料庫或 Entity Framework。

• 通過避免使用如 SQL 伺服器等附加服務來保持容器小巧。

• 資料不可改變——不需要儲存更改； 只需在需要時重置資料。

這種選擇反映了使用現有資源工作的 REST（Representational State Transfer）原則。

理解課程數據結構

Tim 仔細介紹了樣本 JSON 文件的結構：

• ID（整數），

• 預訂（布林值），

• 課程 URL（字串），

• 課程類型（字串），

• 名稱, 課程數量, 課程時長 (小時)（數字），

• 描述, 圖像 URL，

• 以美元計的價格，

• 預覽鏈接。

Tim 在3:29解釋說所有的定價都基於美元； 然而，當地稅（增值稅）可能會改變最終價格。

這些字段中的每一個後來都會映射到 C# 中的一個模型類別 —— 一個構建 ASP.NET Web API 的基礎元素。

創建課程模型類別

進入 .NET Core 編碼，Tim 在一個新的 Models 資料夾中創建了一個 CourseModel.cs 文件。

在 4:47，他使用 Visual Studio 的 "Paste Special > Paste JSON as Classes" 來根據 JSON 結構快速生成一個類。 Tim 指出：

• 正確的 PascalCase 命名（對於 C# web APIs 很重要），

• 必需字串與可空字串（6:02），

• 在一個空字串即可的情況下避免存儲 null。

創建一個強壯的模型類別對於啟用客戶端和伺服器之間的數據通信至關重要。

將數據載入到記憶體中

Tim 通過創建一個 CourseData.cs 類別來繼續以便管理將課程列表載入到記憶體中。

關鍵步驟：

• 使用 System.Text.Json 進行反序列化，

• 設置 PropertyNameCaseInsensitive = true (8:04) 以將 camelCase JSON 對應到 PascalCase C# 字段，

• 使用 Path.Combine (9:04) 進行跨平台文件訪問，

• 確保在處理 Linux 伺服器時的大小寫敏感性 (9:59)。

課程被載入到一個公開的 List 屬性中，保證快速訪問而不需反復打到資料庫。

Tim 在11:04強調如果反序列化失敗，將創建一個新的空列表以防止 null 參考錯誤 —— 這是一種構建強大 API 的最佳實踐。

在依賴注入中註冊課程資料

接下來，Tim 展示了如何使用 AddTransient 在服務容器中註冊 CourseData 類別。

他解釋道，即使資料是只讀的，使用瞬態服務可以避免意外的修改問題。 這種方法符合現代 ASP.NET Core Web API 開發標準。

創建課程端點

在 14:03，Tim 開始為樣本 API 構建端點：

• 在 /courses 的 GET 方法以檢索所有課程，

• 一個擴展方法 AddCourseEndpoints 以便代碼更加簡潔。

這種模組化的方式簡化了擴展您的 Web API 專案 —— 一項在管理大規模 HTTP 服務或多個端點時必需的技術。

Tim 還將發佈的 URL 設置為 Swagger UI 以方便測試。

故障排除：數據類型不匹配

在測試新端點時，Tim 遇到了和 CourseLengthInHours 字段相關的狀態碼錯誤。 他意識到一些課程有小數小時（如 2.5），需要將 int 改為 double。

Tim 修正了 CourseModel，展示了透徹錯誤檢查和在消耗外部網頁資源時尊重數據類型的價值。

通過 ID 查找提高 API 功能

Tim 擴展了功能：

• LoadAllCourses 來檢索所有課程，

• LoadCourseById 以根據 ID 查找課程。

他通過檢查課程是否存在來改善錯誤處理。 如果不存在，Tim 使用 return NotFound() —— 向客戶端返回適當的 HTTP 狀態碼。

這符合 RESTful 架構風格的做法，其中每個 HTTP 方法清楚地傳達操作結果。

通過課程類型和搜尋新增過濾功能

一個簡單的 GET 方法是不夠的——真正的網頁服務需要過濾功能。

Tim 增強了 LoadAllCourses 以接受查詢參數：

• courseType（字串），

• search（字串）。

他解釋了如何使用 String.IsNullOrWhiteSpace 來安全處理可選參數。

課程類型過濾使用 RemoveAll 和 String.Compare，忽略大小寫差異。 搜索課程名稱和簡介使用 .Contains 並進行不區分大小寫的比較。

Tim 測試了如以下場景：

• 過濾 "Master Course"

• 搜尋 "web" 或 "SQL"

• 結合搜尋和課程類型以獲得更細緻的結果

這為通過網頁應用、移動裝置應用或與 HTTP 通信的客戶提供了完全互動的體驗。如需更多詳情，請參考完整 視頻。

最後的想法和下一步

到課程結束時，Tim 已經創建了：

• 一個運行中的 ASP.NET Core Web API，

• 過濾和搜索功能，

• 適當的錯誤處理（NotFound, Ok, 等），

• 支援 Swagger UI 和 OpenAPI 文檔。

Tim 預覽接下來將處理跨來源資源共享（CORS）——這對於允許網際網路客戶端和不同域自由訪問API至關重要。

Tim 結束時給予鼓勵：程式設計有時會遇到障礙，但它是值得的。

結論

按照 Tim Corey 的 視頻，您可以在 Visual Studio 中創建一個新的 Web API 專案，載入樣本數據，建立端點，並實施強大的過濾 —— 所有這些都基於 RESTful 原則和 ASP.NET Core 標準。

無論您是測試網頁、為移動裝置構建 API，還是與現有資源合作，這種設置都可以通過 HTTP 方法確保快速、可靠的數據訪問。

在 .NET Core 中繼續練習這些模式，很快就可以創建出能在客戶端、伺服器和網際網路之間順利通信的健壯網頁服務！