C# Web API – 以Derek Comartin的方法全面了解API結構

了解常見的API結構

Derek從開發者在Visual Studio中創建新的Web API專案時遇到的一個問題開始：

"您應如何結構您的HTTP API？"

他立即承認，Web API專案可以有多種組織方式。 在Derek看到的最常見的資料夾結構中包括：

• 按技術問題分組 – 將模型放在Models資料夾中，將控制器放在Controllers資料夾中，將服務放在Services中。

• 使用Clean Architecture或Onion Architecture – 通過層次分離專案（API、Application、Domain、Infrastructure）來指導相依關係。

• 結合領域驅動設計（DDD）和垂直切片架構 – 按特徵分組端點，但仍有豐富的領域對象。

Derek強調，這些模式中的每一種都可以創建一個RESTful API，使用您所預期的HTTP方法（GET, POST, PUT, DELETE）來操作資源。 但他警告，不要僅僅從資料夾結構中讀取太多內容：

"您可能會看到實體、聚合或領域服務，但這並不意味著代碼真正在使用領域驅動設計——它只是使用這些模式。"

從簡單開始，而非複雜

Derek說他的目標很簡單：

"我想要用這個結構達到的主要目標之一是簡單性。"

Derek選擇ASP.NET Core Minimal APIs而不是跳入一個繁重的.NET Framework風格架構或複製教科書中的模式。為什麼？ 因為它們易於創建API，沒有控制器和樣板代碼的負擔。

當您在Visual Studio或甚至Visual Studio Code中建置新的Web API專案時，您可能會從"新專案對話框"開始並選擇ASP.NET Core Web API。 預設情況下，您將獲得控制器、資料夾和大量的生成工具。 Derek辯稱，開始時使用更小的簡單清晰結構通常更好。

Derek的Web API核心結構

Derek介紹了他使用.NET Core的網頁應用程式結構。 它旨在支持允許不同軟體應用程式交流的常見HTTP服務和RESTful API。

以下是他如何組織他的web API專案：

• Endpoints File – 單個文件中查看API中的所有可用路由。 取代在多個控制器中挖掘，Derek希望快速瀏覽API支持的每個get方法，post方法，put請求或delete請求。

• Common Folder – 包含整個不同軟體系統中使用的共享代碼，如過濾器和擴展。

• Feature Folders – 遵循垂直切片哲學，每個新資源或現有資源都擁有自己的資料夾。 例如，Posts資料夾可能包括GET /posts/{id}、POST /posts、PUT /posts/{id}和DELETE /posts/{id}所需的所有內容。

• Data Folder – 包含數據模型和實體映射。 在這裡，可能使用Entity Framework Core來支持無縫的數據庫整合。

通過按特徵分組端點，Derek避免了邏輯分散在多個無關的資料夾中。

為何他不強求領域驅動設計

Derek過去曾使用過領域驅動設計，但在這個C# Web API結構中，他作出了一個關鍵選擇：

"我們不會使用領域驅動設計。"

相反，他"只是讓數據保持簡單。"他的數據模型是帶有簡單屬性的普通類，例如：

public class Post  
{  
    public int Id { get; set; }  
    public string Title { get; set; }  
}

public class Post  
{  
    public int Id { get; set; }  
    public string Title { get; set; }  
}

沒有多餘的行為被強制添加。 當您發送POST請求創建一個新資源時，API只需保存它。 當您發送帶有id參數的DELETE請求時，它會刪除該資源。

這種方法通過將API端點作為對資源（如Post、User或Comment）操作的動詞（get方法，post方法，put方法，delete方法）來應對表征狀態轉移（REST）的架構樣式。

在Visual Studio中解決方案的導覽

此時，Derek打開了他的Visual Studio解決方案並帶我們進行導覽：

• Endpoints檔案列出了每個路由——無論是GET請求抓取數據，POST請求添加新資源，PUT請求更新數據，還是DELETE刪除現有資源的方法。

• Data資料夾保存實體的映射，如Post、User和Comment——通過Entity Framework連接到數據庫。

• Common資料夾包含HTTP服務的共享邏輯，比如驗證過濾器和擴展。

• 每個特徵資料夾（Posts、Comments、Authentication）都有該資源所需的所有代碼。

這種清晰的專案資料夾佈局避免從過於複雜的專案對話框或分散的controllers資料夾中挖掘。

解剖一個端點

Derek解釋說，在他的ASP.NET Core Web API中，每個端點都是一個自包含的工作單元，並包含三個明確的步驟：

1. 映射 – 定義HTTP方法和路由。 例如，一個delete請求可能將DELETE /posts/{id}映射到一個處理方法。

2. 請求與回應契約 – 每個端點都有其自己的請求正文和回應類型。 這使得HTTP服務更加清晰，並避免創建重複DTO層。

3. 邏輯 – 實際的處理方法，其中API從數據庫中抓取，更新數據模型或返回狀態碼如return CreatedAtAction或return NoContent。

由於Derek使用Minimal APIs，這些處理器是靜態方法。 使用ASP.NET Core，這意味著您可以直接注入依賴項——無需龐大的控制類。

為何Minimal APIs感覺正確

Derek讚揚Minimal APIs的簡單性。 使用ASP.NET Core的最小模板，您可以在Program.cs中僅通過幾行代碼開始web API專案：

var app = WebApplication.CreateBuilder(args).Build();

var app = WebApplication.CreateBuilder(args).Build();

從那里，您可以以一種簡單明瞭的方式添加您的get方法，post方法和put請求。

這種簡單性幫助避免過度設計——這是Derek經常看到當開發者盲目複製nuget包模板或為每個小補點強制新控制類的情況。

計畫如何隨著時間演變為更複雜

Derek給出一個真實的例子："like a post"功能。

• 一開始，它很簡單——檢查是否存在like，如果不存在則添加一個。

• 但後來，軟體應用程序可能需要立即返回like數以供網頁或移動設備使用。

• 為了擴展，您可能通過添加LikeCount屬性到Post數據模型來使數據去正規化。

這帶來了新的挑戰：

• 影響likes的每個put方法或delete方法都必須正確更新計數。

• 若有人在不調用API的情況下添加like記錄，計數就不對了。

Derek展示了隨著複雜性增長，您可能會添加類似於：

• 用於封裝數據訪問的存儲庫模式。

• 處理行為（如遞增LikeCount）的聚合根。

• 保證事件（如"PostLiked"）發布的出站模式。

但他的關鍵觀點很清楚：

"不要從這裡開始。 從簡單開始，只有在需要時才演化。"

結束的示意Derek的要旨

Derek在對C# Web API開發者的主要教訓中結束：

"從簡單開始。"

當您在Visual Studio中使用ASP.NET Core Web API或ASP.NET Web API時，在第一天就很容易過度設計——添加每個您見過的資料夾、模式和NuGet包。

但Derek警告：不要盲目套用解決方案。 了解您需要的HTTP方法，您正在處理的數據，以及您正在促進通信的軟體系統。 一步步建立您的RESTful APIs。

對於那些使用Visual Studio Code或任何其他集成開發環境的人群，他的建議同樣適用：無論是新專案還是現有資源，都要盡可能保持專案結構簡單，僅在面臨現實世界的複雜性需求時才添加模式。

結論

Derek Comartin 的影片不僅僅是搭建C# Web API的指南——這是一個提醒，好的架構始於清晰，而非混亂。 通過介紹他在Visual Studio中的實際ASP.NET Core Web API設置，他展示如何Minimal APIs、特徵資料夾和簡單的數據模型可以為允許不同軟件應用程序無縫通信的RESTful APIs奠定基礎，而不會過於複雜化設計。

如果您想親自看看這種方法的實踐並親耳聽到Derek的觀點，他的影片是一個很好的資源。 他的頻道充滿了關於軟體系統、Web服務和ASP.NET Core開發的同樣具有洞察力的討論——對於任何希望提高自己技能並保持專案乾淨、實用和未來友好的開發者來說，都是必看的。