使用ASP.NET Core 3.x 构建 RESTful API - 1.准备工作

从前写过ASP.NET Core 2.x的REST API文章，本年再更新一下到3.0版本。

先决条件

我在B站有一个非常入门的ASP.NET Core 3.0的视频教程，如果您对ASP.NET Core不相识，就可以先看一下内里的根本知识和API干系的内容，地点是：https://www.bilibili.com/video/av65313713/。

准备知识：ASP.NET Core 和 C#

工具：Visual Studio 2019最新版（VSCode、VS for Mac，Rider等也拼集），POSTMAN

Web API

Web API通常是指“利用HTTP协议并通过网络调用的API”，由于它利用了HTTP协议，所以须要通过URI信息来指定端点。

API是Application Programming Interface的缩写，是软件的外部接口。也就是说，针对某个软件，人们可以知道它的外部功能，但并不知道（也不须要知道）它的内部运作细节，为了从外部调用某些功能，须要指定软件的调用规范等信息，如许的规范就是API。

所以Web API就是一个Web体系，通过访问URI可以与其举行信息交互。

大多数的 Web API 并不是 RESTful API

REST一词是在2000年首次出现的，它是由Roy Fielding博士在《架构风格以及基于网路的软件架构操持》这篇论文中提到的。他为REST风格的API订定了一套束缚规范大概叫架构风格。

所以正确的说，只有符合了Roy Fielding架构风格的Web API才气称作是RESTful API。但是在实际开辟中，偶尔候也有不完全符合Roy Fielding架构风格的情形出现，针对这点我将会在稍后的文章中先容。

MVC模式与RESTful API

本系列文章中我将利用ASP.NET Core 3.0 MVC 来构建 RESTful API。

MVC（Model-View-Controller）我认为是一种紧张用来构建UI的架构模式。对于MVC模式其实有许多种表明存在，但是无论那种表明，它们都会夸大松耦合和关注点分离（separation of concerns）。

也是由于这两点的存在，步伐的可测试性会大大进步，步伐各部门的可复用性也很高。

更多关于MVC的先容，可以看一下微软的官方文档：https://docs.microsoft.com/zh-cn/aspnet/core/mvc/overview?view=aspnetcore-3.0

留意：MVC不是一个完备的应用步伐架构，我认为它紧张是用在展示层。所以实现UI就是MVC的一部门工作。

如何把MVC映射到API

我认为API同样可以看作是UI，它就是为API斲丧者所提供的UI。

让我们把MVC的三部门分别对应到API：

• Model，它负责处理处罚步伐数据的逻辑。这里的Model可以包罗在当前级别获取从存储获取数据的逻辑。但是有一些Model不包罗任何逻辑，比方API所利用的DTO（Data transfer objects），这类的Model会被串行化到相应的body内里。

• View，它是步伐里负责展示数据的那部门。在构建API的时间，View就是数据或资源的展示。如今通常利用JSON格式。

• Controller，它负责View和Model之间的交互。包罗处理处罚用户输入，用API的术语来讲，和API交互的“用户”就是指API的斲丧者，这类用户通常是另一个步伐，比方Angular的SPA步伐。

下面看看MVC这三部门的依靠关系：

Controller和View依靠于Model，Controller依靠于View，这也是分离的一个长处。

换句话说，Controller会选取得当的View来显现给用户，并一同把用户哀求的Model数据带归去。

当API斲丧者发出哀求的时间，在Controller上面的Action将会被触发，Controller会把吸取到的输入数据发送给负责业务处理处罚逻辑或数据访问逻辑的那部门步伐。然后Controller会把Model返回给View，这里的View就是资源的展示（通常是JSON格式）。

接下来我们就是用这套概念和ASP.NET Core 3.0 来创建RESTful API。

但是请留意，通过ASP.NET Core MVC或API模板创建出来的新项目，我们并不会直接得到RESTful（REST架构风格）的API。我们必须在这个根本上，本身构建RESTful的API，由于之前已经提到了，标准的RESTful API有许多束缚和规范。

创建ASP.NET Core 3.0 Web API项目

打开VS2019，选择项目模板ASP.NET Core Web Application：

然后为项目和管理方案起名字，并选择所在目次：

然后选择ASP.NET Core的项目模板：

起主要选择ASP.NET Core 3.0。

这里我选择了API这个模板。在从前，我通常会选择Empty模板，由于别的模板通常包罗许多我不须要的东西，但是ASP.NET Core 3.0的API模板还是比力干净的，可以担当。

末了，由于本课程中不须要利用HTTPS和Docker，所以把这两个东西都勾掉。

剖解 ASP.NET Core 3.0 API 模板项目

点击Create，项目就创建好了：

先看看 appsettings.json：

内里只有默认的Log设置以及允许的Hosts。

而appsettings.Development.json内里：

也只有关于Log的默认设置。

留意：您须要知道appsettings.json 和 appsettings.Development.json之间的关系，关于这点可以看我ASP.NET Core 3.0的入门视频教程，但是更简朴的办法是看一下官方文档：在ASP.NET Core中利用多个情况。

项目模板里另有两个类我们不须要，所以把它删掉，分别是WeatherForecastController和WeatherForecast：

Program.cs：

这里其实就是整个步伐的入口，Main方法负责设置和运行整个Web步伐。

由于这是一个Web项目，所以我们还须要一个宿主（Host），这个宿主就是由下面的CreateHostBuilder方法来负责创建的。该方法起首会创建出一个实现了IHostBuilder接口的类（HostBuilder）的实例，然后调用它的Build方法来创建宿主（范例为Host，实现了IHost接口），末了调用宿主上面的Run方法来运行步伐。

我们暂时不修改这内里的代码，所以统统都会按照项目模板默认的设置举行，留意到下面的方法里我们利用到了Startup这个类：

所以我们来看看Startup类。

Startup.cs

在这个类的构造函数里：

我们看到IConfiguration被注入了，如许就允许我们利用设置信息了，比方appsettings.json内里的设置信息。

下面有一个ConfigureServices方法：

这个方法负责向服务容器内里注册服务，已注册的服务可以通过依靠注入的方式在整个应用步伐的别的地方举利用用。这里的服务是一个比力广义的概念，它就是一个在整个步伐中做一些通用性操纵的组件。

这内里只有一句话：

在3.0之前的版本里，这内里应该写的是services.AddMvc();，实际上在ASP.NET Core 3.0内里如许写也是可以的。但是AddMvc()内里不但仅包罗用于构建API的服务，还包罗许多别的服务，比方构建View视图和TagHelper干系的服务等。而AddControllers()方法只包罗用于构建API的那些服务，比方Controller的支持、Model绑定、Data Annotation和格式化器等等。

最下面另有一个Configure方法：

这个方法利用到了在ConfigureServices方法内里注册和设置的服务，所以这个方法是在ConfigureServices方法之后被调用的。

Configure方法是用来指定ASP.NET Core Web步伐是如何相应每一个HTTP哀求的。换句话说，也就是我们在这里设置哀求的管道，设置的方法就是在这里添加许多中心件（Configure方法内里每一个app.UseXxx就是添加一个中心件，可以查察中心件的官方文档来相识更多）。

在开辟情况的时间，如果有非常发生，那么会展示出一个非常页面：

app.UseAuthorization()，它会为整个Web步伐添加授权的本领。当你须要思量API安全性的时间，这点就很紧张了。通常授权设置是在ConfigureServices方法里完成的，而我如今没有对授权举行设置，但是app.UseAuthorization()仍旧会允许API可以被匿名的访问。

别的这几句话：

这几句话都是用来指定如何把HTTP哀求分配到特定的Controller Action上面的。也就是说这是关于路由的。

很紧张的一点就是：每一个哀求会按照代码的次序穿越全部在这里添加的中心件。但是每一个中心件都有大概将哀求短路，如许的话哀求就不会进入下一个中心件了，而会按照原路返回。

所以，添加中心件的次序非常紧张。如果你把授权中心件放在了Controller的后边，那么纵然须要授权，那么哀求也会先到达Controller并实验内里的代码，如许的话授权就没故意义了。

修改项目启动设置

我喜好利用控制台启动Web步伐，如许可以很直观的看到Log信息。为到达这个目的，可以修改launchSettings.json文件：

修改后，在项目的Debug属性里也有体现：

由于我紧张是利用POSTMAN来调用API，所以我不须要Launch Browser（启动欣赏器）。

运行步伐

可以看到步伐可以正常运行，而且在控制台上有日志的输出。

添加数据存储功能

想要做RESTful API的话，我们还须要数据，这里我准备采取SQLite来作为数据存储，利用Entity Framework Core 作为 ORM来与数据库举行交互。针对Entity Framework Core 3.0 如安在ASP.NET Core 内里利用，官方有个很不错的教程。

下面开始在项目里添加SQLite和EFCore 3.0（这部门官方文档可以点击这里）的支持：

• 起首，须要在我们的项目里通过Nuget添加 Microsoft.EntityFrameworkCore.Sqlite 这个包。

• 然后，还须要安装 Microsoft.EntityFrameworkCore.Tools 这个包，它是用来做迁移的，关于这个包的更多功能表明，可以查察官方文档。

创建Entities

我们先把项目的需求想的简朴一点，暂时我们就做一个公司和公司员工的维护，两个Entity，两个表。

公司（Company）的Entity：

为什么利用Guid作为主键的范例？

员工（Employee）的Entity：

还涉及到一个性别的摆列：

创建DbContext

创建一个文件夹DbContexts，在内里创建一个类名叫RoutineDbContext：

关于这个类的明白并不是本文的重点，想知道详细的表明可以查察这部门的官方文档。

• 这个类须要继承于DbContext，而DbContext须要 DbContextOptions 才气工作，所以我采取了构造函数吸取参数的情势来吸取 DbContextOptions。

• 中心的两个DbSet属性就可以简朴的明白为把Entity映射到了数据库中的一个表。

• 最下面我重写了OnModelCreating 这个方法。在内里，我对两个Entity的某些属性做了一些限定。关于这部门的详细内容，也可以查察官方文档。在方法的末了，我显式的指明白两个Entity之间的关系为一对多关系，并指明白外键。其实按照约定，它们两个之间的一对多关系是默认已经创建的，无需我来指明。

添加种子数据

还是在RoutineDbContext这个类里的OnModelCreating方法里，我添加如下代码来为数据库添加种子数据：

这里只添加了Company数据。

创建Repository

如果只是用来教学RESTful API的话，不利用Repository等Service也行，就是直接在Controller内里利用DbContext也可以担当。但是我还是简朴的写一个Repository吧（这个Repository并不是很规范），否则重复代码大概比力多。

起首看一下ICompanyRepository，也就是Repository的接口合约：

内里的功能我信赖各人应该能看明白吧。

然后看一下实现，CompanyRepository：

比力长。。。

注册服务

在Startup的ConfigureServices方法里把DbContext和Repository注册到容器里：

关于这部门的知识，可以看官方文档：服务生命周期和设置DbContext。

修改Program

为了演示方便，我让数据库在每次步伐启动的时间都会被删掉并重新举行迁移，同时设置好种子数据。这部门内容可查察迁移的官方文档和创建删除API的官方文档。

这里只修改了Main方法：

添加迁移

打开VS2019的Package Manager Console，并输入类似以下的下令来添加迁移：

下令实验成功后，会天生一个Migrations文件夹：

内里包罗着这个这次的迁移类和当前模子的快照。

运行步伐

可以看到实验了一些SQL语句，而且出现的Log都是绿色的Info，这阐明数据库已经创建成功了。

看一下项目文件：

可以看到数据库已经成功的被创建了。

打开数据库：

可以看到种子数据已经成功写入。