用ASP.NET Core 2.0 建立规范的 REST API -- 预备知识

准备项目

上一部分预备知识在这 http://www.cnblogs.com/cgzl/p/9010978.html

如果您对ASP.NET Core很了解的话，可以不看本文, 本文基本都是官方文档的内容。

ASP.NET Core 预备知识

项目配置

假设在项目的根目录有这样一个json文件, 在ASP.NET Core项目里我们可以使用IConfigurationRoot来使用该json文件作为配置文件, 而IConfigurationRoot是使用ConfigurationBuilder来创建的:

可以看到ConfigurationBuilder加载了firstConfig.json文件, 使用的是AddJsonFile这个扩展方法. 调用builder的Build方法会得到一个IConfigurationRoot的实例, 它实现了IConfiguration接口, 随后我们便可以通过遍历它的键值对.

其中json文件里的结构数据都最为键值对被扁平化到IConfiguration里了, 我们可以通过它的key找到对应的值:

像childkey1这种带层次结构的值可以使用冒号 : 作为层次分隔符.

配置文件总会包含这种多层结构的, 更好的办法是把类似的配置进行分组获取, 可以使用IConfiguration的GetSection()方法来获取局部的配置:

当有多个配置文件的时候, 配置数据的加载和它们在程序中指定的顺序是一样的, 如果多个文件都有同一个键的话, 那么最后加载的值将会覆盖先前加载的值.

下面是另一个配置文件:

在firstConfig后加载secondConfig:

最后key1的值是后加载的secondConfig里面的值.

当然了, 如果firstConfig里面有而secondConfig却没有的键, 它的值肯定来自firstConfig.

配置提供商

配置数据可以来自多种数据源, 它们可能是不同格式的.

ASP.NET Core 默认支持从下列方式获得配置:

文件格式(INI, JSON, XML)
命令行参数
环境变量
内存中的.NET对象
未加密的Secret管理存储
加密的用户存储, 例如Azure秘钥库
自定义的提供商

这些东西还是看官方文档吧, 本文使用JSON格式的就够用了.

强类型的配置

ASP.NET Core允许把配置数据映射到一个对象类上面.

针对上面的firstConfig.json文件, 我们创建以下这个类:

然后调用IConfiguration的Bind扩展方法来把键值对集合对值映射到这个强类型对POCO实例里:

在标准的ASP.NET Core 2.0的项目模版里, 加载配置文件的步骤被封装了, 默认或加载appSettings.json 以及 appSettings.{环境}.json.

我记得是封装在这里了:

我把firstConfig.json改名为appSettings.json.

然后在Startup里面可以获得IConfiguration:

从打印结果可以看到, 加载的不只是appSettings里面的内容, 还有系统环境变量的值.

这种情况下, 使用IServiceCollection的Configure扩展方法可以把配置映射到指定的类上面:

同时这也允许在程序的任何地方注入IOptions<FirstConfig>了:

这个Configure方法不仅仅可以映射ConfigurationRoot, 还可以映射配置的一部分:

配置变化

在项目运行的时候, 项目的配置信息可能会发生变化.

当采用的是基于文件的配置时, 如果配置数据有变化了, 我们应该让配置模型重新加载, 这就需要把AddJsonFile里面的配置属性 ReloadOnChange 设置为 true:

这时, 无论在哪各地方使用了IConfigurationRoot和IConfiguration, 它们都会反映出最新的值, 但是IOptions<T>却不行. 即使文件变化了并且配置模型也通过文件提供商进行了更新, IOptions<T>的实例仍然包含的是原始值.

为了让配置数据可以在这种强类型映射的类上体现, 就需要使用IOptionsSnapshot<T>:

IOptionsSnapshot<T> 的开销很小, 可以放心使用

日志

ASP.NET Core 提供了6个内置的日志提供商。

需要使用日志的话，只需注入一个ILogger对象即可，不过该对象首先要在DI容器中注册。

这个ILogger接口主要是提供了Log方法：

记录Log的时候使用Log方法即可：

不过可以看到，该方法参数很多，用起来还是略显麻烦的。

幸运的是，针对Log还有几个扩展方法，他们就简单了很多：

LogCritical，用来记录严重的事情
LogDebug，记录调试信息
LogError，记录异常
LogInformation，记录信息性的事情
LogTrace，记录追踪信息
LogWarning，记录警告信息

在项目中配置和使用Log，只需在Program.cs里调用IWebHostBuilder的ConfigureLogging扩展方法即可:

本例中，我们把log配置成在控制台输出。

如果只是输出到控制台，其实我们就多此一举了，因为CreateDefaultBuilder这个方法里已经做了一些Log的配置，看一下反编译的源码：

可以看到logging的一些配置数据是从整体配置的Logging部分取出来的，然后配置了使用输出到控制台和Debug窗口的提供商。

记录Log的时候，通常情况下使用那几个扩展方法就足够了：

请注意，这里我注入的是ILogger<T>类型的logger，其中T可以用来表示日志的分类，它可以是任何类型，但通常是记录日志时所在的类。

运行项目后，可以看到我记录的日志：

同样也可以在一个类里面把记录的日志分为不同的分类，这时候你可以使用ILoggerFactory，这样就可以随时创建logger了，并把它绑定到特定的区域：

不知道您有没有发现上面这几个例子中日志输出的时候都有个数字 [0], 它是事件的标识符。因为上面的例子中我们没有指定事件的ID，所以就取默认值0。使用事件ID还是可以帮助我们区分和关联记录的日志的。

每次写日志的时候, 都需要通过不同的方式指明LogLevel, LogLevel表明的是严重性.

下面是ASP.NET Core里面定义的LogLevel(它是个枚举), 按严重性从低到高排序的:

Trace = 0, 它可以包含敏感拘束, 默认在生产环境中它是被禁用掉的.

Debug = 1, 也是在调试使用, 应该在生产环境中禁用, 但是遇到问题需要调试可以临时启用.

Information = 2, 用来追踪应用程序的总体流程.

Warning = 3, 通常用于记录非正常或意外的事件, 也可以包括不会导致应用程序停止的错误和其他事件, 例如验证错误等.

Error = 4, 用于记录无法处理的错误和异常, 这些信息意味着当前的活动或操作发生了错误, 但不是应用程序级别的错误.

Critical = 5, 用于记录需要立即处理的事件, 例如数据丢失或磁盘空间不足.

None = 6, 如果你不想输出日志, 你可以把程序的最低日志级别设置为None, 此外还可以用来过滤日志.

记录的日志信息是可以带参数的, 使用消息模板(也就是消息主题和参数分开), 格式如下:

同样也支持字符串插值:

第二种方式代码的可读性更强一些, 而且它们输出的结果没有什么区别:

但是对于日志系统来说, 这两种方式是不一样的. 通过消息模板的方式(消息和参数分开的方式), 日志提供商可以实现语义日志或叫做结构化日志, 它们可以把参数单独的出入到日志系统里面进行单独存储, 不仅仅是格式化的日志信息.

此外, 用重载的方法, 记录日志时也可以包含异常对象.

日志分组

我们可以使用相同的日志信息来表示一组操作, 这需要使用scope, scope继承了IDisposable接口, 通过ILogger.BeginScope<TState>可以得到scope:

使用scope, 还有一点需要注意, 需要在日志提供商上把IncludeScopes属性设置为true:

您可以发现, 日志被输出了两遍, 这是因为WebHost.CreateDefaultBuilder方法里面已经配置使用了AddConsole()方法, 我再配置一遍的话就相当于又添加了一个输出到控制台的日志提供商.

所以, 我可以不采用这个构建模式创建IWebHost, 改为直接new一个:

这样就正确了. 可以看到日志信息的第一行内容是一样的, 第二行是各自的日志信息.

日志的过滤

我们可以为整个程序设定日志记录的最低级别, 也可以为某个日志提供商和分类指定特定的过滤器.

设置全局最低记录日志的级别使用SetMinimumLevel()扩展方法:

如果想完全不输出日志的话, 可以把最低记录的级别设为LogLevel.None.

我们还可以为不同场景设置不同的最低记录级别:

然后分别建立这两个分类的logger, 并记录:

查看输出结果, 已经按配置进行了过滤:

这里可以使用完整的类名作为分类名:

然后使用ILogger<T>即可:

针对上面这个例子, 我们还可以使用配置文件:

相应的, 代码也需要改一下:

输出的效果是一样的.

日志提供商

ASP.NET Core 内置了6个日志提供商:

Console, 使用logging.AddConsole()来启用.
Debug, 使用logging.AddDebug()来启用. 它使用的是System.Diagnostics.Debug的Debug.WriteLine()方法, 由于Debug类的所有成员都是被[Conditional("DEBUG")]修饰过了, 所以无法被构建到Release Build里, 也就是生产环境是无法输出的, 除非你把Debug Build作为部署到生产环境😰.
EventSource, 使用logging.AddEventSourceLogger()来启用. 它可以把日志记录到事件追踪器, 它是跨平台的, 在windows上, 会记录到Event Tracing for Windows (ETW)
EventLog (仅限Windows), 使用logging.AddEventLog()来启用. 它会记录到Windows Event Log.
TraceSource (仅限Windows),, 使用logging.AddTraceSource(sourceSwitchName)来启用. 它允许我们把日志记录到各种的追踪监听器上, 例如 TextWriterTraceListener
Azure App Service, 在本地运行程序的时候, 这个提供商并不会起作用, 部署到Azure App Service的.NET Core程序会自动采用该提供商, .NET Core无须调用logging.AddAzureWebAppDiagnostics();该方法. 它会把日志记录到Azure App Service app的文件系统还会写进Azure Storage账户的blob storage里.

第三方日志提供商

第三方的提供商有很多: Serilog, NLog, Elmah.IO, Loggr, JSNLog等等.

处理异常

ASP.NET Core 未开发人员提供了一个异常信息页面, 它是运行时生成的, 它封装了异常的各种信息, 例如Stack trace.

可以看到只有运行环境是开发时才启用该页面, 上面我抛出了一个异常, 看看访问时会出现什么结果:

这就是异常页面, 里面包含异常相关的信息.

注意: 该页面之应该在开发时启用, 因为你不想把这些敏感信息在生产环境中暴露.

当发送一个请求后, HTTP机制提供的响应总是带着一个状态码, 这些状态码主要有:

1xx, 用于通知报告.
2xx, 表示响应是成功的, 例如 200 OK, 201 Created, 204 No Content.
3xx, 表示某种重定向,
4xx, 表示客户端引起的错误, 例如 400 Bad Request, 401 Unauthorized, 404 Not Found
5xx, 表示服务器错误, 例如 500 Internal Server Error.

默认情况下, ASP.NET Core 项目不提供状态码的细节信息, 但是通过启用StatusCodePagesMiddleware中间件, 我们可以启用状态码细节信息:

然后当我们访问一个不存在的路由时, 就会返回以下信息:

我们也可以自定义返回的状态码信息:

OK, 预备知识先介绍到这, 其它相关的知识在建立API的时候穿插着讲吧.

项目开始模板

非常的简单, 先看一下Program.cs:

我们使用了WebHost.CreateDefaultBuilder()方法, 这个方法的默认配置大约如下:

采用Kestrel服务器, 使用项目个目录作为内容根目录, 默认首先加载appSettings.json, 然后加载appSettings.{环境}.json. 还加载了一些其它的东西例如环境变量, UserSecrect, 命令行参数. 然后配置Log, 会读取配置数据的Logging部分的数据, 使用控制台Log提供商和Debug窗口Log提供商, 最后设置了默认的服务提供商.

然后我添加了自己的一些配置:

使用IIS作为反向代理服务器, 使用Url地址为http://localhost:5000, 使用Startup作为启动类.

然后看Startup:

主要是注册mvc并使用mvc.

随后建立Controllers文件夹, 然后可以添加一个Controller试试是否好用:

可选项目配置

注意, 在使用VS2017启动项目的时候, 上面有很多选项:

为了开发时方便, 我把IISExpress这个去掉, 打开并编辑这个文件:

删掉IISExpress的部分, 然后修改一下applicationUrl:

然后启动选项就只剩下一个了:

如果你喜欢使用dotnet cli, 可以为项目添加dotnet watch, 打开并编辑 MyRestful.Api.csproj, 添加这行即可:

然后命令行执行 dotnet watch run 即可, 每次程序文件发生变化, 它都会重新编译运行程序:

为项目添加EntityFrameworkCore 2.0

关于EFCore 2.0的知识, 还是请看官方文档吧, 我也写了一篇非常非常入门级的文章, 仅供参考: http://www.cnblogs.com/cgzl/p/8543772.html

新建立两个.NET Core class library类型的项目:

这几个项目的关系是: MyRestful.Infrastructure 需要引用 MyRestful.Core, MyRestful.Api 需要引用其他两个.

并把它们添加到MyRestful.Api项目的引用里.

然后要为MyRestful.Infrastructure项目添加几个包, 可以通过Nuget或者Package Manager Console或者dotnet cli:

Microsoft.EntityFrameworkCore.SqlServer (我打算使用内存数据库, 所以没安装这个)

Microsoft.EntityFrameworkCore.Tools

然后在MyRestful.Infrastructure项目里面建立一个DbContext:

再建立一个Domain Model, 因为Model和项目的合约(接口)一样都是项目的核心内容, 所以把Model放在MyRestful.Core项目下:

然后把这个Model放到MyContext里面:

在Startup.cs里面注册DbContext, 我使用的是内存数据库:

这里要注意: 由于使用的是内存数据库, 所以迁移等一些配置都可以省略了....

做一些种子数据:

这时需要修改一下Program.cs 来添加种子数据:

好的, 到现在我写一些临时的代码测试一下MyContext:

直接从数据库中读取Domain Model 然后返回, 看看效果(这次使用的是POSTMAN):

可以看到, MyContext是OK的.

到这里, 就会出现一个问题, Controller的Action方法(也就是Web API吧)应该直接返回Domain Model吗?

你也可能知道答案, 不应该这样做. 因为:

像上面例子中的Country这样的Domain Model对于整个程序来说是内部实现细节, 我们肯定是不想把内部实现细节暴露给外部的, 因为程序是会变化的, 这样就会对所有依赖于这个内部实现的客户端造成破坏. 所以我们需要在内部实现外面再加上另外一层, 这层里面的类就会作为整个程序的公共合约或公共接口(界面的意思, 不是指C#接口).

可以把这件事想象比喻成组装电脑:

组装电脑机箱里有很多零件: 主板, 硬盘, CPU, 内存.....这就就是内部实现细节, 而用户能看到和用到的是前后面板的接口和按钮, 这就是我所说的电脑机箱的公共合约或公共接口. 更重要的是, 组装电脑的零件可能会更新换代, 也许添加一条内存, 换个固态硬盘.....但是所有的这些变化都不会改变(基本上)机箱前后面板的接口和按钮. 这个概念对于软件程序来说是一样的, 我们不想暴露我们的Domain Model给客户端, 所以我们需要另外一套Model类, 它们要看起来很像我们的Domain Model, 但是这两种model可以独立的进化和改变.

这类Model会到达程序的边界, 作为Controller的输入, 然后Controller把它们串行化之后再输出.

用REST的术语来说, 我们把客户端请求服务器返回的对象叫做资源(Resources).

所以我会在MyRestful.Api项目里建立一个Resources文件夹, 并创建一个类叫做CountryResource.cs (以前我把它叫ViewModel或Dto, 在这里我叫它Resource, 都是一个意思):

现在来说, 它的属性和Country是一样的.

现在的问题是我要把MyContext查询出来的Country映射成CountryResource, 你可以手动编写映射关系, 但是最好的办法还是使用AutoMapper库(有两个), 安装到MyRestful.Api项目:

AutoMapper 和 AutoMapper.Extensions.Microsoft.DependencyInjection

然后我们要做两个映射配置文件, 分别是Domain Model ==> Resource 和 Resource ==> Domain Model:

当然了, 也可以做一个配置文件, 我还是做一个吧:

然后在Startup里面注册AutoMapper即可:

修改Controller测试下:

结果是OK的:

Repository 模式

概念不说了, 你可以把Repository想象成就是一堆Domain Models, 我们可以使用这个模式来封装查询等操作. 例如下面红框里面的查询:

这个查询有可能在整个项目中的多个地方被使用, 在稍微大一点的项目里可能会有很多类似的查询, 而Repository模式就是可以解决这个问题的一种方式.

所以我在MyRestful.Infrastructure项目里建立Repostitories文件夹并建立CountryRepostsitory类:

这里需要注入MyContext, 暂时只需要一个查询方法.

现在Repository做好了, 为了在Controller里面使用(依赖注入), 我们需要为它抽取出一个接口, 因为我们不想让Controller与这些实现紧密的耦合在一起, 我们需要做的是把Controller和接口给耦合到一起, 这也就是依赖反转原则(DIP, 也就是SOLID里面的D, 高级别的模块不应该依赖于低级别的模块, 它们都应该依赖于抽象):

此外, 单元测试的时候, 我们可以用实现了IRepository的假Repository, 因为单元测试的时候最好不要依赖外界的资源, 例如数据库, 文件系统等, 最好只用内存中的数据.

所以先抽取接口:

然后配置DI:

在这里ASP.NET Core 提供了三种模式注册实现给接口, 它们代表着不同的生命周期:

Transient: 每次请求（不是指HTTP Request）都会创建一个新的实例，它比较适合轻量级的无状态的（Stateless）的service。
Scope: 每次http请求会创建一个实例。
Singleton: 在第一次请求的时候就会创建一个实例，以后也只有这一个实例，或者在ConfigureServices这段代码运行的时候创建唯一一个实例。

由于Repository依赖于DbContext, 而DbContext在ASP.NET Core项目配置里是Scope的, 所以每次HTTP请求的生命周期中只有一个DbContext实例, 所以IRepository就应该是Scope的.

修改Controller, 注入并使用IRepository, 去掉MyContext:

经测试, 结果是一样的, 我就不贴图了.

还有一个问题, 因为每次HTTP请求只会存在一个MyContext的实例, 而引用该实例的Repository可能是多个. 也就是说会存在这种情况, 某个Controller的Action方法里, 使用了多个不同的Repository, 分别做了个新增, 修改, 删除等操作, 但是保存的时候还是需要MyContext来做, 把保存动作放到任何一个Repository里面都是不合理的. 而且我之前讲过应该把Repository看作是Domain Models的集合, 例如list, 而list.Save()也没有什么意义. 所以Controller还是依赖于MyContext, 因为需要它的Save动作, 还是需要解耦.

之前讲的使用Repository和依赖注入解耦的方式很大程度上较少了重复的代码, 而把Controller和EFCore解耦还有另外一个好处, 因为我有可能会把EFCore换掉, 去使用Dapper 😂, 因为如果项目比较大, 或者越来越大, 有一部分业务可能会需要性能比较好的Micro ORM来代替或者其它存储方式等. 所以引用EFCore的地方越少, 就越容易替换.

这时, 就应该使用Unit Of Work 模式了, 首先我添加一个IUnitOfWork的接口, 我把它放在MyRestful.Core项目的interfaces文件夹下了:

只有一个异步方法SaveAsync(). 然后是它的实现类UnitOfWork:

就是这样, 如果你想要替换掉Entity Framework Core的话, 只需要修改UnitOfWork和Repository, 无须修改IUnitOfWork和IRepository, 因为这些接口是项目的合约, 可以看作是不变的 (所以IRepository也应该放在MyRestful.Core里面, 这个以后再改).

然后注册DI: