第3章创建最小（Minimal APIs）API应用程序

1.最小API概述

在ASP.NET Core的广阔天地里，"最小API应用程序"如同一把轻巧而强大的瑞士军刀，专为迅速构建HTTP API而生。这些API天生具备将数据编织成JSON语言的能力，无论是与单页应用（SPA）的细腻对话，还是与手机APP的快捷交互，都能游刃有余。它们常与前端领域的明星（如Angular、React.js等）或移动开发平台并肩作战，共同编织出流畅的用户体验和高效的数据流转。

踏入ASP.NET Core的API构建之旅，最小API（Minimal APIs）仿佛为我们铺设了一条高速通道。相较于传统的MVC或Razor Pages路径，它以一种近乎魔术的方式，让我们仅凭少量代码与配置，便能驾驭RESTful风格的接口。无需深陷于控制器与视图模型的繁复编织中，只需在项目的心脏地带Program.cs，通过一连串流畅的调用与匿名函数的巧妙编排，即可勾勒出API的蓝图——从路径规划到行为定义，再到请求处理的每一个细节。

更令人称道的是，最小API倡导的是一种“简约而不简单”的哲学。它鼓励我们摒弃那些可能沦为负担的传统搭建仪式（基架），直截了当地声明API的使命与功能，拒绝冗余的中间环节，让程序架构如同清风拂面，既清爽又高效。

最小API无疑是ASP.NET Core中的一颗璀璨明珠，它以其卓越的简化能力与灵活性，极大地减轻了开发者的负担，加速了API的创建、测试与部署进程，同时确保了代码的清晰与维护的便捷。在.NET 6及后续版本中，这一模式更是得到了前所未有的强化与推广，成为了构建高效、轻量级API的优选方案。

喂喂！少年们，别被那些听起来高大上的词给吓住了！其实，它们都是网络世界里的一些好朋友，咱们应该把它们变得亲切易懂。

首先，“HTTP API”，你可以想象成是网络上的小邮局。这个邮局有一套特殊的规则（就是HTTP协议），它帮助不同的软件小伙伴（比如网页、手机应用、其他服务器等）互相传递信件（数据和信息）。当你想要从某个小伙伴那里拿点啥或者给点啥时，你就通过这个小邮局来发请求和收回复。

再来，“SPA”，它其实是“单页应用”的简写。想象一下，你打开了一个超级厉害的网页，它就像是一本厚厚的书，但这本书不用翻页就能看到所有内容。SPA就是这样一个网站，它在你第一次加载后，后续的内容变化都是在这一个页面上完成的，不需要重新加载整个页面，感觉就像是在玩一个超流畅的游戏。

至于“RESTful”，它不是什么宗教！它是“Representational State Transfer”的缩写，听起来很复杂，但其实是一种设计风格，就像是我们整理房间的方式。RESTful告诉我们，应该把网络资源（比如网页上的信息）想象成一本本书或者一个个盒子，然后用HTTP的那些方法（GET、POST、PUT、DELETE）来对这些资源进行操作，就像是我们从书架上拿书、放书、改书或者扔书一样。

所以，少年们，现在是不是觉得这些词都变得亲切多了呢？网络世界里的这些小伙伴，其实都是来帮助我们更好地交流、分享和工作的。

2.基础知识

HTTP API就像是网络世界里的“翻译官”，它用HTTP协议这种大家都懂的语言，来制定了一套交流的规矩。这样，不同的软件系统，比如网页、手机应用、其他服务器等，就能通过这个“翻译官”来互相发消息、要数据或者给指令了。

想象一下，你（客户端）想要从图书馆（服务器）借本书，你就通过HTTP API这个“翻译官”给图书馆发个请求，说：“伙计，我想借这本书。”图书馆（服务器）收到后，就会按照你的要求找书，然后告诉你找没找到，这就是响应。整个过程，都是通过HTTP API这个“翻译官”来完成的，它确保了你们之间能顺利沟通。

HTTP API的特点：

遵循HTTP协议：就像打电话有拨号规则一样，HTTP API也规定了怎么发请求、怎么收响应的一套标准。比如，用GET方法就像是说“给我这个”，POST方法就像是“帮我存这个”。
RESTful风格：这是一种很流行的交流方式，它把网络上的东西想象成一本本书（资源），然后通过HTTP方法来操作这些书。比如，用GET看书，POST写新书，PUT改书，DELETE撕书。
无状态：就是每次交流都是独立的，图书馆不会记得你上次来借了什么书，除非你每次都明确告诉它。
易用：HTTP API通常会有一份“使用说明书”，告诉你怎么发请求、要带哪些参数、响应长啥样，这样你就很容易上手了。
灵活：你可以选择用JSON、XML等不同语言来写请求和响应，还可以选择同步、异步等不同方式来交流，就像你可以选择写信、打电话或者视频聊天一样。

在这里提到的“API”（Application Programming Interface，应用程序编程接口）是一种软件中介，它定义了一套协议、规范或标准，使得不同的软件应用程序之间能够进行通信和数据交换。简而言之，API是不同软件应用程序之间的“桥梁”，允许它们互相“对话”和“交流”。

HTTP API在现代软件开发中超级重要，它让不同的软件系统能轻松地一起工作，分享数据，就像让各种肤色国籍的小朋友们在同一个游乐场里愉快地玩耍一样。

3.创建的你第一个最小API应用程序

就像武侠小说《射雕英雄传》里的柯镇恶大侠，他是个直性子，喜欢直截了当。他常说的“看我眼色行事”，三秒后画面一转柯大侠被敌人打倒在地怒视对手高声叫嚷“要杀便杀”。
在这里插入图片描述
启动 Visual Studio 2022 并选择“创建新项目（N）”。

在“创建新项目”对话框中：

在“搜索模板”搜索框中输入 空。
选择“ASP.NET Core 空”模板，然后选择“下一步”。
在这里插入图片描述

在这里插入图片描述
在配置新项目对话框中输入”项目名称“为BookQuerySystem（可自行命名），自行选择位置（L），单击下一步；

在配置其他信息对话框中，框架（F） 选择”.NET 8.0(长期支持)“、勾上配置HTTPS(H) 选择框，单击创建；

在几秒钟的等待之后Visual Studio 2022 使用默认项目模板为我们创建了一个叫BookQuerySystem的项目。这是一个简单的项目，接下来我们按 Ctrl+F5来运行它。
按Ctrl+F5 是在非调试情况下启动应用，在这情况下我们依然可以更改代码、保存文件和刷新浏览器查看代码更改后的页面效果。

如果项目没有配置使用 SSL，Visual Studio 会弹出对话框：

你可以把SSL想象它是一个超级保镖，专门负责在计算机网络上保护信息的安全传输。当你决定使用SSL来保护你的数据时，这个保镖就会开始工作，它会确保你的数据在发送和接收的路上都是加密的，就像是给数据穿上了一层隐形的防护衣。这样，就算是有人想偷看或者拿走这些数据，也因为它们是加密的而看不懂、拿不走，从而保护了数据的安全，防止了泄露给未经允许的人。

如果信任 IIS Express SSL 证书，请选择“是”；
如果你同意信任开发证书，请选择“是”；
以上内容看不懂没有关系，目前你只需要选择"是"。
如果项目已配置使用 SSL，则不会弹出对话框。
同时我们也可以从“调试”菜单中以调试或非调试模式启动应用；

同时我们也可以从“调试”菜单中以调试或非调试模式启动应用
在这里插入图片描述
下图是应用在Microsoft Edge浏览器上的运行效果！

你瞧见了啥？是那句经典的“Hello World!”吗？我猜不是，我看到的是咱们的老伙计——BookQuerySystem项目，这回咱们又挖了个新坑，而且这个坑比上次还大！不过别怕，我坚信小伙伴们可以齐心协力把这个技术上的坑给填平。

也许这是你亲手打造的第一个应用程序，就算你还没亲手敲下一行代码，也得给你个大大的赞，你已经迈出了成功的第一步！谁说编程非得是枯燥无味的学习呢？我们可不愿意这样，咱们要学得开心，学得有趣！编程路上，咱们一起说说笑笑，共同享受那份创造的乐趣吧！

3.深入聊聊最小API

之前我们聊过，在ASP.NET Core的世界里，有个新玩意儿叫“最小API”（Minimal API）。它就像是一个超级简洁的API开发小能手，专门用来帮我们更快更容易地搭建Web应用程序,它是一个ASP.NET Core的API开发模型。

到底啥是最小API？

最小API是ASP.NET Core从6.0版本开始推出的一个新功能。它就像是用函数式编程的方法，通过一连串的命令来设置路由、处理请求和中间件，超级直接，没有那么多复杂的控制器和动作方法。路由、处理请求和中间件等等你现在还不理解的概念都会在后文中一一讲解。

为啥要有最小API？

Microsoft为了让大家开发Web应用更简单、更高效，就推出了这个最小API。它帮我们省去了很多传统的样板代码，让代码看起来更清爽，开发起来也更快。

最小API有啥好处？

代码少：因为没有了控制器和动作方法，代码自然就少了，看起来也更简单。
依赖少：不需要额外的NuGet包，就用ASP.NET Core自带的包就行，项目更清爽。
路由配置直观：用链式调用的方式设置路由，一看就懂，好上手。
应用轻量：代码少、依赖少，所以应用启动快，占用的内存也少。

啥时候用最小API？

当你需要快速搭建一个小型的、专门干一件事的Web API，或者是在微服务架构中构建服务时，最小API就是你的好帮手。它能让你快速高效地完成任务。

举个栗子

看看我们刚才创建的历上最简单的最小API示例：

// 首先，我们创建一个Web应用的构建器  
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
 
// 然后，用构建器构建出应用  
WebApplication app = builder.Build();  
  
// 接下来，我们用MapGet方法设置了一个路由，当访问根URL（/）时，就返回一个“Hello World!”  
app.MapGet("/", () => "Hello World!");  
  
// 最后，启动应用  
app.Run();

在这个例子里，我们创建了一个Web应用，并设置了一个简单的路由，当有人访问这个应用的根URL时，它就会说“Hello World!”。

下面让我们逐行解析代码：

// 首先，我们创建一个Web应用的构建器 
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

在.NET世界里，特别是当你使用ASP.NET Core或者更新版的.NET（比如.NET 8.0及以上，本文使用.NET 8.0），WebApplication类里面有个超级有用的方法叫做CreateBuilder(args)。这个方法返回的WebApplicationBuilder类（builder是WebApplicationBuilder类的实例）就像是搭建Web应用的“包工头”，它帮你开始搭建整个工程。它返回的这个叫做“WebApplicationBuilder类”的东西可以用来设置你的应用，比如怎么管理依赖、记录日志、添加中间件等等。

想象一下，“构建器（Builder）”模式就像是你建房子时一步步添砖加瓦的过程。在WebApplicationBuilder的世界里，你不需要一下子把所有材料都搬来，而是可以一边建一边加材料。这样，你的代码就不会乱糟糟的，而是很清晰。WebApplication.CreateBuilder(args)是ASP.NET Core 里用来初始化和配置Web应用的一个超级重要的步骤。它让你可以灵活又方便地搭建和配置你的现代Web应用，就像玩游戏《我的世界》一样。

具体来说，WebApplication.CreateBuilder(args)这个方法做了以下几件大事：

初始化“服务员”：它首先找了一个“服务员”（依赖注入容器），这个“服务员”负责给应用程序里的其他部分提供需要的“服务”（比如数据库连接、其他工具类等）。
设置日志本：它帮你准备了一个日志本，这样你就可以在应用程序的不同地方记录信息、警告或者错误了。
配置房子和家具：它帮你设置了“房子”（Web应用程序的主机）和“家具”（应用程序的配置），包括选择用什么“门牌号”（URL）来访问你的应用，还有选择用哪个“装修公司”（比如Kestrel服务器）来帮你运行网站。
提供定制服务：它还很贴心，提供了很多可以定制的地方，比如你可以通过一些方法来告诉它你还需要哪些额外的“服务”（服务配置）、怎么记录日志等。
完成建造：虽然WebApplicationBuilder本身不是直接用来运行应用的，但它有一个Build()方法，可以造出一个WebApplication的实例(app)，这个实例就是用来实际运行你的Web应用的。

// 然后，用构建器构建出应用 
WebApplication app = builder.Build();

在ASP.NET Core（从.NET 6.0开始）里，MapGet 方法是个超级好用的工具。它帮你告诉程序：“伙计，如果有人通过GET方式访问这个特定的网址（比如网站的根目录，就是直接输网址的那种），你就执行我给你的这段代码，然后告诉访问者‘Hello World!’”。

看这行代码：

app.MapGet("/", () => "Hello World!");

它做了三件事，倍儿简单：

设置网址：它用“/”这个符号说：“我要设置的是网站的根目录的网址。” 这意味着，不管你是直接输入网址还是点击网站首页的链接，只要地址栏里是网站的根目录，这行代码就会起作用。
编写回复：它接着写了个小函数：“() => ‘Hello World!’”。这个函数就像个自动回复机，没有复杂的参数，就是当有人访问时，直接回复“Hello World!”。
加入处理流程：MapGet 方法实际上是把这个小函数放到了一个叫做“请求处理管道”的地方。想象一下，这个管道就像是网站的门卫，负责检查每个进来的请求。当发现有人通过GET方式访问根目录时，它就会找到这个小函数，让它来回复访问者。
而且，虽然这里只是简单地回复了一个文本，但ASP.NET Core很聪明，它会自动把这个文本包装成一个网页的形式发送给访问者，还会告诉浏览器这个内容是纯文本（text/plain）。如果你想发送HTML、JSON或其他东西，也可以告诉ASP.NET Core怎么做。

这行代码就是告诉ASP.NET Core：“如果有人访问网站的首页，你就帮我回复一句‘Hello World!’”吧。

// 最后，启动应用  
app.Run();

app.Run() 的作用很简单，就像是你告诉ASP.NET Core：“伙计，我已经把网站的一切都准备好了，包括怎么处理不同的网页请求，怎么跟数据库打交道等等。现在，请你把网站的‘大门’打开，开始接受外面人的访问吧！”这里的“大门”其实就是HTTP服务器，它负责接收来自互联网上的请求，并且根据我们之前设置好的规则来处理这些请求。所以，app.Run() 就是那个按下“开门”按钮的命令。

我们提到的“HTTP服务器”，它就像是ASP.NET Core网站背后的那个超级厉害的“接待员”——Kestrel。Kestrel非常厉害，它能跨平台工作，不管你的网站是建在Windows、Linux还是macOS上，它都能搞定。它的主要工作就是站在那儿，等着接收来自互联网上的各种请求，然后按照我们之前设定好的规则来处理这些请求。

其实，当你准备好网站，告诉ASP.NET Core“伙计，我要开张迎客啦！”的时候，Kestrel这个“接待员”就会自动站出来，开始它的工作，也就是打开“大门”，迎接那些来自互联网的请求。而app.Run()这个命令，虽然在最小API的世界里我们通常不用直接说，但它是那个让一切准备就绪，告诉Kestrel“是时候站岗了”的信号。所以，归根结底，我们说的“请把网站的‘大门’打开”，就是让Kestrel这个超级“接待员”开始它的工作，接收并处理那些来自四面八方的HTTP请求。

接下来让我们再次按 Ctrl+F5来运行应用程序：
在这里插入图片描述
https://localhost:7260/ 这个网址就像是一把钥匙，它能帮你打开你电脑上某个特定的“门”。下面我用更简单的话来说说这个网址的各个部分：

协议部分（https://）：这就像是你去一个地方要走的路线。这里的路线是“安全的网页路线”，也就是HTTPS。它就像给你的数据传输加了个密码锁，保证别人偷看不了你发出去和收进来的信息。
主机名（localhost）：这就像是你要去的那家店的名字，但这里特别的是，它其实指的就是你自己的电脑。所以，你不需要上网去找，直接在自己电脑上就能找到这个“店”。
端口号（:7260）：每个“店”里可能有很多不同的房间，每个房间都有自己的门牌号，这里的7260就是那个“房间”的门牌号。它告诉电脑：“嘿，我要找的是那个监听在7260号房间的服务。”
路径（/）：这就像是你进了“店”之后，要去找的东西放在哪里。这里的“/”表示的是最开始的地方，也就是那个“房间”的入口，或者是店里的默认展示区。
把这些都加起来，https://localhost:7260/ 就是告诉电脑：“请通过安全的网页路线，去我的电脑上的7260号房间，找到那个默认的东西给我看。” 这个东西可能是一个你正在开发的网站，或者是一个API接口，反正是你电脑上的一个Web服务或应用程序的“家”。因为是在你自己电脑上，所以这个网址只有你自己能用，别人是进不去的，除非你给了他们权限。

既然小伙伴们已经踏进了探险的门槛，接下来咱们就一起瞧瞧这门里面藏着啥宝贝如何？
很显然我们要写一个图书查询系统，咱们就直接去瞅瞅里面有没有书吧。在浏览器上面的那个地址栏里，咱们输入网址https://localhost:7260/Books，然后回车，就能进去看看了。
在这里插入图片描述
哇塞！我们打开了那扇神秘的门，结果却发现里面有个小插曲——原来是个错误在等着我们呢！~ 不过没关系，解决问题就是探险的一部分嘛！

您看啊，就像您走进了一个空荡荡的房间（这个房间的门牌号就是“/”），里面啥都没有放，对吧？那么，当您想要找一本书，特别是想要找放在标有“Books”牌子的书架上的书时，您当然会找不到，因为这个房间里根本就没有书架，更没有“Books”这个牌子的书架了。

同样的道理，当您在浏览器里输入https://localhost:7260/Books，想要访问您网站上的“Books”页面时，因为您之前没有在“/”这个门后面放上任何关于“Books”的东西，所以服务器就会告诉您：“哎呀，我找不到您要的这个页面啊！”然后，它就给您显示了一个404错误页面，这个页面就像是服务器在对您说：“抱歉，您走错门了，这里没有您要找的东西。”

所以，这个404错误页面其实是服务器自动生成的，用来告诉您：“您请求的资源不存在。”这样您就知道需要去检查是不是URL写错了，或者网站管理员是不是还没把您想要的东西放到网站上呢。
在接下来的一章里，我们会手把手教你打造一个图书查询系统，每一步都会细细讲解，让你清楚明白每个知识点是怎么用的，就像跟着菜谱一步步做出美味佳肴一样简单易懂。今天夜深了，休息，休息，先到这里吧！