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、应用程序、领域、基础架构）对项目进行拆分，以指导依赖关系。

• 将领域驱动设计（DDD）与垂直切片架构相结合--按功能对端点进行分组，但仍拥有领域丰富的对象。

Derek 强调，这些模式中的每一种都可以创建 RESTful API，使用您所期望的 HTTP 方法（GET、POST、PUT、DELETE）来处理资源。 但他警告说，不要仅从文件夹结构中读出太多东西：

"您可能会看到实体、聚合或域服务，但这并不意味着代码真的在进行域驱动设计--它只是在使用这些模式"。

化繁为简

Derek 说他的目标很直接：

"我想通过这种结构实现的主要目的之一就是简洁"。

Derek 没有跳入繁重的 .NET Framework 风格架构或复制教科书中的模式，而是选择了 ASP.NET Core Minimal API。为什么？ 因为这些工具可以轻松创建 API，而不需要控制器和模板代码。

当您在 Visual Studio 甚至 Visual Studio Code 中构建一个新的 Web API 项目时，您可能会从新建项目对话框开始，然后选择 ASP.NET Core Web API。 默认情况下，您将获得控制器、文件夹和大量脚手架。 Derek 认为，从小处着手--简单、干净的结构--往往更好。

德里克 Web API 的核心结构

德里克介绍了他使用 .NET Core 的网络应用程序结构。 它支持常见的 HTTP 服务和 RESTful API，允许不同的软件应用程序进行通信。

以下是他如何组织网络 API 项目的：

• 端点文件 - 用于查看 API 中所有可用路由的单一文件。 Derek 希望快速了解 API 支持的每种获取方法、发布方法、放入请求或删除请求，而不是翻阅多个控制器。

• 通用文件夹 - 存放不同软件系统中使用的过滤器和扩展名等共享代码。

• 功能文件夹 - 按照垂直切分的理念，每个新资源或现有资源都有自己的文件夹。 例如，Posts 文件夹可能包括 GET /posts/{id}、POST /posts、PUT /posts/{id} 和 DELETE /posts/{id} 所需的所有内容。

• 数据文件夹 - 包含数据模型和实体映射。 在这里，可能会使用 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 端点视为动词（get 方法、post 方法、put 方法、delete 方法），作用于帖子、用户或评论等资源，从而体现了表征状态转移 (REST) 的架构风格。

在 Visual Studio 中浏览解决方案

此时，德里克打开了他的 Visual Studio 解决方案，并带我们进行了参观：

• 端点文件列出了每个路由，无论是获取数据的 GET 请求、添加新资源的 POST 请求、更新数据的 PUT 请求，还是删除现有资源的 DELETE 方法。

• 数据文件夹中包含通过Entity Framework连接到数据库的实体（如帖子、用户和评论）的映射。

• 通用文件夹包含 HTTP 服务的共享逻辑，如验证过滤器和扩展。

• 每个功能文件夹（帖子、评论、身份验证）都包含该资源所需的所有代码。

这种简洁的项目文件夹布局避免了翻阅过于复杂的项目对话框或散乱的控制器文件夹时的混乱。

分解端点

Derek 解释说，他的 ASP.NET Core Web API 中的每个端点都是一个独立的工作单元，有三个明确的步骤：

1.映射 - 定义 HTTP 方法和路由。 例如，一个删除请求可能会将 DELETE /posts/{id} 映射到一个处理程序方法。

2.请求和响应合同 - 每个端点都有自己的请求体和响应类型。 这将使 HTTP 服务更加清晰，并避免产生层层重复的 DTO。

3.逻辑 - 实际的处理方法，即 API 从数据库中获取数据、更新数据模型或返回状态代码（如 return CreatedAtAction 或 return NoContent）的方法。

由于 Derek 使用 Minimal API，因此这些处理程序都是静态方法。 有了 ASP.NET Core，这意味着您可以直接注入依赖关系--无需庞大的控制器类。

为什么最小化 API 感觉正确

Derek 对 Minimal API 的简洁性大加赞赏。 利用 ASP.NET Core 的最小模板，只需在 Program.cs 中添加几行代码，您就可以启动一个 Web API 项目：

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

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

在这里，您可以直接添加 get 方法、post 方法和 put 请求。

这种简洁性有助于避免过度工程化--当开发人员盲目复制 NuGet 包模板或为每个次要端点强行创建新的控制器类时，Derek 经常会看到这种情况。

复杂性如何随时间演变

Derek 举了一个真实的例子："喜欢帖子 "功能。

• 起初，工作很简单--检查是否存在同类，如果不存在就添加一个。

• 但随后，软件应用程序可能需要为网页或移动设备即时返回同类计数。

• 为了扩大规模，您可以通过在 "发布 "数据模型中添加 LikeCount 属性来对数据进行去规范化处理。

这就带来了新的挑战：

• 每个影响 "喜欢 "的 put 方法或 delete 方法都必须正确更新计数。

• 如果有人在未调用 API 的情况下添加了同类记录，则计数是错误的。

Derek 指出，随着复杂性的增加，您可以添加以下模式：

• 封装数据访问的存储库模式。

• 处理行为（如递增 LikeCount）的聚合根。

• 确保事件（如 "PostLiked"）发布的发件箱模式。

但他的关键点很明确：

"不要从这里开始。 先从简单的开始，必要时再发展"。

总结 Derek 的收获

最后，Derek 回到了他为 C# Web API 开发人员提供的主要课程：

"从简单开始"

当您在 Visual Studio 中使用 ASP.NET Core Web API 或 ASP.NET Web API 时，很容易从第一天起就过度工程化--添加您见过的所有文件夹、模式和 NuGet 包。

但 Derek 警告说：不要盲目套用解决方案。 了解您所需的 HTTP 方法、您正在处理的数据以及您正在启用的软件系统之间的通信。 逐步构建您的 RESTful API。

对于那些使用 Visual Studio Code 或其他集成开发环境的人来说，他的建议是正确的：无论是新项目还是现有资源，都要尽可能保持项目结构简单，只有在现实世界的复杂性需要时才添加模式。

结论

Derek Comartin 的视频不仅仅是构建 C# Web API 的指南，它还提醒我们，好的架构始于清晰，而非杂乱。 他通过在 Visual Studio 中实际设置 ASP.NET Core Web API 的过程，展示了 Minimal API、功能文件夹和简单明了的数据模型如何构成 RESTful API 的基础，从而实现不同软件应用程序之间的无缝通信，而不会使设计过于复杂。

如果您想了解这种方法的实际效果，并亲耳聆听 Derek 的观点，他的视频是一个很好的资源。 他的频道充满了关于软件系统、Web 服务和 ASP.NET Core 开发的同样有见地的讨论--任何希望提高自己的技术并保持项目简洁、实用和未来友好的开发人员都必须关注。