(废弃)ASP.NET Core 6 Web API 最佳实践探索(1) - 入门与简介

发表于 更新于 分类于 ， 阅读次数：

(2022年4月12日)弃更说明

这个系列的文章姑且需要告一段落，原因非常简单——关于最佳架构的讨论，无论是在Github上，还是在微软官方提供的实例/电子书中，都已经得到了较多的讨论。我仔细思考后，发现没有手把手开始再写一次的必要。

目前，关于ASP.NET Core架构的最佳实践问题，我打算先静下心来，仔细读一读相关的书籍和源代码，相关内容的更新，也暂时将切换形式为读书笔记之类的内容。

毕竟，如果不读书，一昧输出自己的观点只能是误人子弟，圈地自萌罢了。

前言

终于考完期末考试了，趁着我的手机游戏还在清空体力，让我们先开个题目，即:

ASP.NET Core 6 Web API 最佳实践探索

开这个坑，主要是想记录一下自己写ASP.NET Core Web API程序时候，学习到的一些关于程序架构设计，项目的拆分和设计这方面的内容，或许这会使得我未来写项目时候，不至于像现在这样东拼西凑。

写了一半以后回来的补充: 写着写着发现文体又变成了新手入门体，面面俱到，然而这样不太利于这一系列文章的展开。所以，文章假定各位读者具有一定的Web开发基本常识。这样接下来会轻松很多。

关于内容准确性的警告

在本文撰写的过程中，尽管本人已经查阅了一部分资料，比较了所见到的不同方法，但由于个人能力的有限，我无法保证我接下来介绍的方法就是标题所说的 最佳实践 。我只能尽我所能，至少能将写的部分解释清楚。如果在阅读本系列文的过程中，有任何疑问，或是发现了什么谬误，再或是认为有更优秀的写法，欢迎通过本站点左侧站点概览下的邮箱按钮私信本人，还请各位多多批评指教。

预备环境

接下来的程序编写，使用的编辑器是Visual Studio Code，配备Microsoft发布的C#插件。

虽然我也很喜欢Visual Studio没错，而且VS2022以来，自动补全功能提升非常明显。但毕竟那玩意不开源，我还是希望在介绍一种方法时候，尽可能用自由开源的道路来介绍，包括下面的一些选择也是如此（甚至其实接下来的操作，我会使用VSCodium来替代Visual Studio Code）。

.NET版本号已使用6.0。请使用LTS版本。安装请见.NET | Free. Cross-platform. Open Source.。

对于RESTful API的调试，虽然直接用curl命令，或是直接用浏览器是可以，但不太方便。最著名的API调试工具莫过于Postman，但其并非开源产品。所以我还会推荐一个同样好用的开源替代产品Insomnia。

项目背景

参考微软官网文档上的案例，我们也从一个待办事项应用程序开始。

不过，我们可以稍微做一点调整，使得我们的案例不失一般性。同时，也能更好坚持开源这一原则。

我们要做的待办事项网站，具有这些特点。

  • 遵循RESTful API设计规范
  • 更好的分层架构设计
  • 日志系统
  • 采用MariaDB数据库(取代了微软官方文档中爱用的SQLite或Microsoft SQL Server)
  • JWT认证机制

罗马不是一日建成的，让我们一点点开始吧。

从基本的.NET 6 Web API应用开始

现在假设环境已经配置完毕，让我们创建第一个项目。

找个你喜欢的空白文件夹，打开命令提示符，输入:

1
2
dotnet new webapi -o MyTodo.Api
dotnet new gitignore

这里，MyTodo.Api是我们为这个项目起的名字，按你喜欢的就好。而第二行是向我们的项目文件夹，添加.NET默认的.gitignore文件，在创建git仓库时将合理忽略一些非关键代码文件。就算暂时用不到git，创建一个也没有问题。

在VSCode里面打开这个文件夹。展开任意一个.cs后缀的文件。等待VSCode为我们配置好相关组件，并添加必要的依赖项。

创建的新项目结构

这样，我们的第一个Web API应用就创建好了。是不是非常简单？

尝试着运行一下吧。按下F5键，或是切换到运行和调试面板，点击播放按钮。

默认情况下，VSCode在项目启动成功后，会打开浏览器，自动访问我们的网站。这里，不同电脑上，不同网站应用程序使用的端口号在新建项目时随机指定，需要各位在接下来测试过程中留心替换。假设在这里，我们的HTTPS端口号是12345。

由于没有指定默认的路由，直接访问会报告404错误。因此我们转到Controllers/WeatherForecastController.cs文件。

WeatherForecastController.cs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
using Microsoft.AspNetCore.Mvc;

namespace MyTodo.Api.Controllers;

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    // ...
    [HttpGet(Name = "GetWeatherForecast")]
    public IEnumerable<WeatherForecast> Get()
    {
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateTime.Now.AddDays(index),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = Summaries[Random.Shared.Next(Summaries.Length)]
        })
        .ToArray();
    }
}

注意到类WeatherForecastController方法上的Route标签，其后的[controller]是一个特别变量，指代控制器类的类名前缀(在本例中为WeatherForecast)。这样，[Route("[controller]")]标签的意思是，它下方的控制器，路由地址为该控制器类的名称。所以，我们在我们访问的链接后添加这一串，变成https://localhost:12345/WeatherForecast。

用Insomnia看看。

Insomnia发送GET请求到WeatherForecast

发现问题

这个只是.NET创建的模板项目，起到的是实例的作用。如果我们仿照这样的写法，编写我们的待办事项程序，我们很快就发现，这样的代码，并不好。我们将在接下来的文章中继续分析。