範例Web API的介紹

Tim 開始時解釋為什麼建立一個新的Web API專案對開發者來說這麼重要。 無論您是為移動裝置構建、Web應用程式還是其他軟體應用程式，擁有一個輕量的範例API可以讓測試更快、更順利。

Tim 表示，專案結束時，我們將會擁有：

• 使用ASP.NET Core和.NET Core的簡約API，

• 支援OpenAPI（Swagger UI）的文件化API，

• 健康檢查，

• 模擬錯誤和延遲，

• 以Docker容器和VPS伺服器進行部署。

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

設置專案及範例資料

Tim 開始在Visual Studio這款由Microsoft推出的知名整合開發環境中結構化Web API專案。

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

Tim的設定要點：

• 使用JSON文件作為範例資料，可以避免需要資料庫或Entity Framework。

• 透過避免額外服務（如SQL伺服器）來保持容器小巧。

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

此選擇反映了使用現有資源的REST（表現層狀態轉移）原則。

了解課程資料結構

Tim詳細介紹了範例JSON文件的結構：

• ID（整數），

• 預訂（布林值），

• 課程URL（字串），

• 課程型別（字串），

• 名稱、課程數量、課程時長（數字），

• 描述、圖片URL，

• 以美元計算的價格，

• 預覽連結。

Tim在3:29時解釋，所有定價都是基於美元； 不過，本地稅（增值稅）可能會改變最終價格。

這些字段中的每一個稍後都映射到C#中的模型類—這是在構建ASP.NET Web API中關鍵元素。

建立課程模型類

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

在4:47時，他使用Visual Studio的"特別貼上 > 貼上JSON作為類"功能，立即根據JSON結構生成一個類模板。 Tim 訴說以下幾點：

• 適當的PascalCase命名（對於C# web API非常重要），

• 必要與可空字串（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<CourseModel>屬性中，確保快速存取而無需反覆存取資料庫。

Tim在11:04時強調說，如果反序列化失敗，將建立一個新的空列表以防止空引用錯誤 - 這是一個構建強大API的最佳實踐。

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

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

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

建立課程端點

在14:03時，Tim開始為範例API構建端點：

• 使用GET方法在/courses路徑下獲取所有課程，

• 使用拓展方法AddCourseEndpoints以達到更清晰的程式碼。

這種模塊化方法簡化了擴展您的Web API項目—當管理大型HTTP服務或多個端點時，一種必要的技術。

Tim也將啟動URL設定為Swagger UI，便於測試。

疑難排解：資料型別不匹配

在測試新端點時，Tim發現與CourseLengthInHours字段有關的狀態碼錯誤。 他意識到某些課程擁有小數小時（如2.5），需要使用double而非int。

Tim修正了CourseModel，展示了全面錯誤檢查和尊重資料型別在使用外部Web資源時的重要性。

改善API與ID查找功能

Tim擴展了其功能：

• LoadAllCourses以獲取所有課程，

• LoadCourseById以通過ID找到課程。

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

這符合RESTful的架構風格實踐，其中每個HTTP方法清楚地交流操作結果。

新增課程型別篩選和搜尋功能

一個簡單的GET方法是不夠的—真正的Web服務需要篩選功能。

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

• courseType（字串），

• search（字串）。

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

過濾courseType使用RemoveAll和String.Compare，忽略大小寫差異。 查找課程名稱和簡短描述使用.Contains進行不區分大小寫比較。

Tim測試了例如：

• 過濾"Master Course"

• 過濾"web"或"SQL"

• 結合搜尋和課程型別以獲得更精煉結果

這為跨Web應用程式、移動應用程式或通過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中練習這些模式，很快您就會建立出能夠在客戶端、伺服器與互聯網之間平穩通信的堅固Web服務！