C#應用程式

C# Web API – 使用 Derek Comartin 方法完整介紹 API 架構

Tim Corey

44m 57s

在開始一個C# Web API專案時，開發者常常面對著如何組織程式碼的眾多選擇，感到不知所措。您應該遵循分層ASP.NET Core Web API模式嗎？或者，您應該堅持使用Visual Studio中的預設範本中的控制器資料夾嗎？或者，您應該嘗試像Minimal APIs這樣的現代風格嗎？

在他的影片《Keep Your Project Structure Simple!》中，來自CodeOpinion.com的Derek Comartin 採取了一種有見地但實用的新穎觀點。他分享了他的想法，介紹如何構建和組織一個Web API，以適用於現實世界的軟體系統，專注於真正重要的事：簡單。

本文將循著Derek的影片一步一步操作，指導您如何為ASP.NET Core Web API專案架構一個具有清晰性、可維持性和實際規模化能力的項目。

查看常見的API結構

Derek 一開始就問了一個一旦在Visual Studio中建立新的Web API專案通常會遇到的問題：

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

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

按技術關注點分組 – 將模型放在Models資料夾中，控制器在Controllers資料夾中，服務在Services中。
使用Clean Architecture或Onion Architecture – 將專案按層次 (API、Application、Domain、Infrastructure) 來劃分以引導依賴關係。
結合Domain-Driven Design (DDD) 與垂直切片架構 – 通過功能對端點進行分組，但仍保留具體的域物件。

Derek強調，這些模式中的每一種都可以建立使用您期望的HTTP方法（GET、POST、PUT、DELETE）來處理資源的RESTful API。但他警告不要只從文件夾結構讀的太多：

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

從簡單開始，而不是複雜

Derek表示他的目標清楚明確：

"我想要達到的一個主要目標是這個結構保持簡單。"

而不是直接採用複雜的.NET Framework風格架構或從教科書中複製模式，Derek選擇了ASP.NET Core Minimal APIs。為什麼？因為它們使得建立API變得容易而不需要控制器和程式碼樣板的冗餘。

當您在Visual Studio或甚至Visual Studio Code中建立新的Web API專案時，您可能會從New Project Dialog開始並選擇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避免了將邏輯散佈在多個不相關文件夾的情況。

為什麼他不強迫使用Domain-Driven Design

Derek曾在過去使用Domain-Driven Design，但在這個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; }  
}

Public Class Post
    Public Property Id As Integer
    Public Property Title As String
End Class

Public Class Post
    Public Property Id As Integer
    Public Property Title As String
End Class

沒有必要行為填塞進去。當您發送POST請求來建立新資源時，API只會保存它。當您發送DELETE請求並附帶id參數時，會刪除該資源。

這種方法體現了Representational State Transfer (REST) 的架構風格，將API端點視為代替資源。例如，get方法、post方法、put方法、或delete方法。

在Visual Studio中逐步遍歷解決方案

此時，Derek打開他的Visual Studio解決方案並給我們一個瀏覽：

Endpoints文件列出了每條路徑 – 不論是GET請求獲取資料，POST請求新增新資源，PUT請求更新資料，還是DELETE方法刪除現有資源。
Data資料夾保存實體Post、User和Comment的映射 - 透過Entity Framework連接到資料庫。
Common資料夾包含HTTP服務的共用邏輯，例如驗證過濾器和擴展。
每個Feature Folder (Posts、Comments、Authentication) 擁有該資源所需的全部程式碼。

這種乾淨的專案資料夾佈局，避免了通過一個過於複雜的專案對話或一個凌亂的控制器文件夾中的麻煩。

分解一個端點

Derek解釋說，每個端點在他的ASP.NET Core Web API中是一個獨立的工作單位，具有三個明確步驟：

映射 – 定義HTTP方法和路徑。例如，一個DELETE請求可能將DELETE /posts/{id}映射到一個處理方法中。
請求和回應契約 – 每個端點都有自己的請求正文和回應型別。這使HTTP服務變得更清晰，避免建立重複的DTO層。
邏輯 – 實際的處理方法，在那裡API從資料庫中擷取資料，更新資料模型，或返回狀態碼像是return CreatedAtAction或return NoContent。

因為Derek使用Minimal APIs，這些作為靜態方法的處理程式。與ASP.NET Core結合，這意味著您可以直接注入依賴項 - 不需要龐大的控制器類。

為什麼Minimal APIs感覺對

Derek稱讚Minimal APIs的簡單性。利用ASP.NET Core的minimal範本，您可以僅用幾行Program.cs程式碼便啟動一個Web API專案：

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

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

Dim app = WebApplication.CreateBuilder(args).Build()

Dim app = WebApplication.CreateBuilder(args).Build()

從那裡，您可以以簡單明了的方式新增您的get方法、post方法和put請求。

這種簡單性，幫助避免過度設計—Derek看到太多開發者盲目複製nuget包範本或者為每一個小端點強制新增新的控制器類。

如何隨著時間推移，複雜性會演變

Derek給出了一個實際範例："like a post"功能。

一開始很簡單 - 檢查是否存在like，若無則新增一個。
但以後，該軟體應用可能需要即時返回like計數給網頁或移動裝置。
為了擴展，您可能會透過為Post資料模型新增一個LikeCount屬性來進行資料去正規化。

這開啟了新的挑戰：

每個影響likes的put方法或delete方法必須正確更新計數。
如果有人在不呼叫API的情況下新增了一個like記錄，計數會錯誤。

Derek展示了當複雜性增長時，您可能會新增以下模式：

Repository模式，用於封裝資料存取。
使用Aggregate Roots來處理行為（如增加LikeCount）。
採用Outbox Pattern來保證事件（如"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 API打下基礎，而不過於複雜化設計。

如果您想親眼看看這種方法如何操作，並親自聽取Derek的觀點，他的影片是一本極好的資源。他的頻道充滿了同樣具有洞見力的討論關於軟體系統、網路服務和ASP.NET Core開發——對於任何希望提高其技藝並保持其項目乾淨、實用和適應未來的開發者來說都是必看的。