【ASP.NET Core 基础知识】–Web API–创建和配置Web API（一）

一、简介

Web API（Web Application Programming Interface）的重要性在于其在现代软件开发中扮演着关键的角色。以下是一些关于Web API重要性的方面：

跨平台交互：

Web API允许不同平台、不同技术栈的应用程序进行通信。无论是Web应用、移动应用、桌面应用还是其他服务，它们都可以通过Web API实现数据和功能的共享。

服务间通信：

在分布式系统中，不同的服务需要相互通信。Web API提供了一种标准化的方式，使得这些服务可以以一致的方式进行数据交换和功能调用。

前后端分离：

Web API促使了前后端分离的架构。通过将前端和后端分开，开发团队可以更好地专注于各自的领域，实现更灵活、可维护的代码。

移动应用开发：

移动应用通常需要与服务器进行数据交互。通过使用Web API，移动应用可以轻松地与后端服务通信，获取和更新数据，实现应用与服务器的有效连接。

微服务架构：

在微服务架构中，各个服务通过API进行通信。Web API提供了一种标准的、松耦合的方式，使得不同的微服务可以独立开发、部署和扩展。

数据交换格式：

Web API通常使用标准的数据交换格式，如JSON或XML。这使得不同系统之间可以轻松地共享数据，同时也提高了数据的可读性和可理解性。

开放性和互操作性：

使用Web API，企业和组织可以提供对其服务和数据的开放接口，促进合作和集成。这种开放性有助于创造更加灵活和可扩展的应用生态系统。

安全性：

Web API提供了安全机制，通过身份验证和授权，确保只有授权的应用或用户能够访问特定的资源和功能。

Web API在现代软件开发中是不可或缺的组成部分，它们促使了系统的模块化、可扩展性和互操作性，为开发人员提供了强大的工具来构建各种类型的应用程序。

二、创建Web API项目

2.1 使用命令行工具创建项目

你可以使用命令行工具（Command-Line Interface，CLI）来创建Web API项目。以下是在命令行中使用.NET CLI创建项目的基本步骤：

打开命令行终端：

打开你喜欢使用的命令行终端，如Windows的命令提示符（Command Prompt）、PowerShell，或者在Linux/macOS中的终端。

使用cd命令进入你希望存放项目的目录，例如：
```
cd path/to/your/projects
```

运行dotnet new命令：

使用dotnet new命令创建项目。在这里，我们使用webapi模板来创建一个Web API项目。
```
dotnet new webapi -n YourApiName
```
这里-n参数用于指定项目的名称。

使用cd命令进入新创建的项目目录：
```
cd YourApiName
```

运行项目：

使用dotnet run命令启动应用程序。这将会编译并运行你的Web API应用：
```
dotnet run
```
应用程序启动后，你应该能够看到输出信息，包括应用程序正在监听的端口。

测试API：

打开浏览器或使用工具（如Postman）访问https://localhost:5001/weatherforecast，这是默认的示例API端点。

通过以上步骤，你就成功地使用.NET CLI创建了一个简单的Web API项目。你可以根据项目的需要进行进一步的开发和配置。记得查看.csproj文件和Startup.cs文件，这些文件包含了项目的配置和启动设置。

2.2 使用Visual Studio创建项目

在Visual Studio 2022中创建Web API项目的步骤如下：

选择创建新项目：选择“创建新项目”。
选择ASP.NET Core Web API项目模板：在创建新项目的窗口中，你需要选择“ASP.NET Core Web API”项目模板。
配置新项目：接下来，你需要输入项目名称，选择项目位置。
配置其他信息：在配置新项目的过程中，你还需要配置其他信息，比如框架、身份验证类型、配置HTTPS、启用Docker、启用OpenAPI支持等。
创建项目：最后，点击“创建”按钮，即可创建一个新的ASP.NET Core Web API项目[1][2][4]。

三、配置路由和控制器

3.1 理解路由的基本概念

在Web API中，路由是决定如何将HTTP请求映射到控制器和操作方法的过程。理解Web API路由的基本概念对于构建和设计API端点是至关重要的。以下是一些关键的概念：

路由模板（Route Template）：

路由模板定义了API端点的URI结构，它决定了请求应该如何被匹配到相应的控制器和操作方法。路由模板使用占位符来表示变量，例如 {controller}, {action}, {id}等。示例：[Route("api/[controller]/{id}")]

HTTP谓词（HTTP Verb）：

路由不仅仅是URI的映射，还与HTTP谓词相关联，例如GET、POST、PUT、DELETE等。通过在控制器的操作方法上使用[HttpGet]、[HttpPost]等特性，可以指定每个操作方法响应的HTTP谓词。

默认路由：

默认路由是一个通用的路由规则，将URI映射到控制器和操作方法。在ASP.NET Core中，默认路由的模板通常是{controller=Home}/{action=Index}/{id?}，表示控制器默认为Home，操作方法默认为Index，而id是可选的。

属性路由（Attribute Routing）：

ASP.NET Core允许使用属性路由在控制器和操作方法上直接定义路由模板。这样可以使路由信息更直观，例如：[Route("api/[controller]/{id}")]。属性路由是一种常用的方式，特别是在RESTful API中。

约束（Constraints）：

路由约束允许你指定路由参数的格式或值的范围。例如，你可以使用正则表达式来确保id参数是数字，或者使用[Range]属性进行范围验证。

路由生成（Link Generation）：

在构建URL时，路由生成允许你以类型安全的方式引用API端点。在视图、控制器或其他地方，你可以使用Url.Action或Url.RouteUrl等方法，这样你就不需要硬编码URL，而是依赖于路由模板和参数。

路由匹配优先级：

当有多个路由模板与请求匹配时，系统会选择最匹配的路由。匹配的优先级取决于模板中的占位符和约束。系统会尽量选择最具体的路由。

路由中间件：

在ASP.NET Core中，路由是通过路由中间件来处理的。路由中间件在HTTP请求到达控制器之前，负责解析URI并确定要执行的控制器和操作方法。

3.2 创建控制器类

在.NET 6中，使用命令行工具可以很方便地创建Web API控制器类。以下是使用.NET CLI命令创建控制器类的基本步骤：

进入项目目录，使用 cd YourApiName 进入项目目录。
运行以下命令来创建一个控制器类：
```
dotnet add controller -n YourControllerName
```
这里 -n 参数用于指定控制器的名称。
上述命令执行后，你会看到控制器类文件被创建在 Controllers 文件夹下。默认情况下，控制器类的名称会以 Controller 结尾，例如 ValuesController.cs。
打开创建的控制器类文件，你将看到一个默认的控制器类，其中包含一些示例代码，通常会有一些示例操作方法（Action）。你可以根据你的需求修改、添加或删除这些操作方法。示例控制器类的结构如下：

using Microsoft.AspNetCore.Mvc;
using System;
using System.Collections.Generic;

namespace YourApiName.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class YourControllerNameController : ControllerBase
    {
        // GET: api/YourControllerName
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET: api/YourControllerName/5
        [HttpGet("{id}")]
        public string Get(int id)
        {
            return "value";
        }

        // POST: api/YourControllerName
        [HttpPost]
        public void Post([FromBody] string value)
        {
        }

        // PUT: api/YourControllerName/5
        [HttpPut("{id}")]
        public void Put(int id, [FromBody] string value)
        {
        }

        // DELETE: api/YourControllerName/5
        [HttpDelete("{id}")]
        public void Delete(int id)
        {
        }
    }
}

3.3 定义路由规则

在ASP.NET Core Web API中，路由规则定义了如何映射HTTP请求的URI到相应的控制器和操作方法。有几种方式可以定义路由规则，其中最常见的是通过特性路由（Attribute Routing）和全局路由配置。以下是这两种方式的简要说明：

特性路由（Attribute Routing）特性路由是在控制器和操作方法上使用特性来定义路由模板的一种方式。这样的定义更直观，通常用于RESTful API。下面是一个简单的示例：

[ApiController]
[Route("api/[controller]")]
public class YourControllerNameController : ControllerBase
{
    // GET: api/YourControllerName
    [HttpGet]
    public IEnumerable<string> Get()
    {
        return new string[] { "value1", "value2" };
    }

    // GET: api/YourControllerName/5
    [HttpGet("{id}")]
    public string Get(int id)
    {
        return "value";
    }

    // POST: api/YourControllerName
    [HttpPost]
    public void Post([FromBody] string value)
    {
    }

    // PUT: api/YourControllerName/5
    [HttpPut("{id}")]
    public void Put(int id, [FromBody] string value)
    {
    }

    // DELETE: api/YourControllerName/5
    [HttpDelete("{id}")]
    public void Delete(int id)
    {
    }
}

在上面的例子中，[Route] 特性用于指定控制器的基础路由，而在操作方法上使用的[HttpGet]、[HttpPost]等特性表示对应的HTTP谓词和相对于控制器基础路由的路径。

全局路由配置另一种方式是在 Startup.cs 文件中进行全局路由配置。在 ConfigureServices 方法中使用 AddControllers 方法，并通过 Configure 方法进行路由配置。以下是一个简单的例子：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

在这个例子中，MapControllers 方法会默认使用约定路由，即根据控制器和操作方法的命名规范自动生成路由规则。例如，YourControllerNameController 的 Get 方法将匹配 /YourControllerName。你还可以在 Startup.cs 文件中使用 MapControllerRoute 方法进行自定义全局路由配置，例如：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "api/{controller}/{action}/{id?}");
    });
}

在这个例子中，MapControllerRoute 方法用于定义一个命名路由，其中 {controller}、{action}、{id} 是占位符，表示对应的控制器、操作方法和可选的标识符。这样的配置可以灵活地适应你的项目需求。

Tip：你可以根据项目的特点选择适合的方式，有时候也可以混合使用特性路由和全局路由配置。

四、数据模型和DTOs

4.1 创建数据模型

在ASP.NET Core Web API中，数据模型通常用于表示应用程序中的实体，这些实体可以映射到数据库表、API的输入输出等。以下是创建一个简单数据模型的基本步骤：

在项目中创建一个模型类：

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

在上面的示例中，创建了一个名为 Product 的数据模型，该模型具有 Id、Name 和 Price 属性。

在你的项目中创建一个用于表示实体的类。这个类可以包含属性、方法和其他成员，以便在应用程序中使用。

使用数据注解（Optional）：

using System.ComponentModel.DataAnnotations;

public class Product
{
    public int Id { get; set; }

    [Required]
    public string Name { get; set; }

    [Range(0.01, double.MaxValue, ErrorMessage = "Price must be greater than 0.")]
    public decimal Price { get; set; }
}

在上面的示例中，使用了 Required 和 Range 属性来添加数据验证规则。

可以使用数据注解来为模型类提供更多的信息，例如数据验证、显示名称等。例如，使用 System.ComponentModel.DataAnnotations 命名空间中的注解：

使用数据上下文（Optional）：

using Microsoft.EntityFrameworkCore;

public class ApplicationDbContext : DbContext
{
    public DbSet<Product> Products { get; set; }

    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
        : base(options)
    {
    }
}

在上面的示例中，创建了一个 ApplicationDbContext 类，该类继承自 DbContext 并包含一个用于表示 Product 实体的 DbSet 属性。

如果你打算将模型映射到数据库，通常会使用Entity Framework Core等ORM工具，并创建一个数据上下文（DbContext）来处理数据库交互。

配置数据上下文（Optional）：

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));

    // Other configurations...
}

在上面的示例中，使用了SQL Server数据库，你需要在 appsettings.json 文件中配置数据库连接字符串。

在 Startup.cs 中配置数据库连接和数据上下文：

这样，你就创建了一个简单的数据模型，并可以选择性地将其映射到数据库中。在Web API中使用这个数据模型，可以在控制器中操作它，例如获取、创建、更新和删除数据。

4.2 使用DTOs传输数据

在ASP.NET Core Web API中，使用DTOs（数据传输对象）是一种常见的做法，它允许你在客户端和服务端之间传输数据，同时也能够控制传输的数据内容。以下是使用DTOs传输数据的基本步骤：

创建DTO类：

public class ProductDTO
{
    public string Name { get; set; }
    public decimal Price { get; set; }
}

在上面的示例中，创建了一个名为 ProductDTO 的DTO类，该类包含 Name 和 Price 属性。

创建一个DTO类，该类包含你想要在客户端和服务端之间传输的数据属性。通常，DTO类应该只包含那些在传输时需要的属性，而不是整个实体模型。

在控制器中使用DTOs：

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly ApplicationDbContext _context;

    public ProductsController(ApplicationDbContext context)
    {
        _context = context;
    }

    // POST: api/products
    [HttpPost]
    public IActionResult CreateProduct([FromBody] ProductDTO productDTO)
    {
        if (productDTO == null)
        {
            return BadRequest("Product data is null.");
        }

        // Convert DTO to entity model
        var product = new Product
        {
            Name = productDTO.Name,
            Price = productDTO.Price
        };

        // Add to database
        _context.Products.Add(product);
        _context.SaveChanges();

        // Return a response with DTO
        var responseDTO = new ProductDTO
        {
            Name = product.Name,
            Price = product.Price
        };

        return Ok(responseDTO);
    }
}

在上面的示例中，CreateProduct 操作方法接收一个 ProductDTO 对象，将其转换为实体模型（Product），然后将实体模型添加到数据库。最后，通过创建另一个DTO对象来表示返回给客户端的数据。

在你的控制器中使用DTO类来处理传入和传出的数据。通常，在API端点的参数中使用DTO类来接收客户端的数据，同时在返回结果中使用DTO类来传递数据给客户端。

Tip：使用DTOs的好处在于可以减少在网络上传输的数据量，提高性能，并确保只传输客户端所需的数据。此外，DTOs还提供了更好的灵活性，因为你可以根据需要定制DTO类的属性。

4.3 数据模型验证

在ASP.NET Core Web API中，你可以使用数据注解（Data Annotations）和 Fluent Validation 等方式对数据模型进行验证。以下是其中两种常见的方法：

使用数据注解使用 System.ComponentModel.DataAnnotations 命名空间中的注解来对数据模型进行验证。这些注解包括 [Required]、[StringLength]、[Range] 等。示例：

using System.ComponentModel.DataAnnotations;

public class Product
{
    public int Id { get; set; }

    [Required(ErrorMessage = "Name is required")]
    public string Name { get; set; }

    [Range(0.01, double.MaxValue, ErrorMessage = "Price must be greater than 0.")]
    public decimal Price { get; set; }
}

在上面的示例中，[Required] 用于确保 Name 属性不能为空，而 [Range] 用于确保 Price 属性在指定的范围内。

使用 Fluent ValidationFluent Validation 是一种基于流畅的语法，可以在 .NET Core 应用程序中实现强大的验证规则。首先，你需要安装 FluentValidation.AspNetCore 包：

dotnet add package FluentValidation.AspNetCore

然后，创建一个验证器类，继承 AbstractValidator<T> 类，并在构造函数中定义验证规则。示例：

using FluentValidation;

public class ProductValidator : AbstractValidator<Product>
{
    public ProductValidator()
    {
        RuleFor(product => product.Name)
            .NotEmpty().WithMessage("Name is required");

        RuleFor(product => product.Price)
            .GreaterThan(0).WithMessage("Price must be greater than 0.");
    }
}

在 Startup.cs 文件的 ConfigureServices 方法中，注册验证器：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
            .AddFluentValidation(fv => fv.RegisterValidatorsFromAssemblyContaining<ProductValidator>());
}

然后，你可以在控制器中使用验证器来验证模型。如果验证失败，将返回包含错误信息的 BadRequest 响应。示例：

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly IValidator<Product> _validator;

    public ProductsController(IValidator<Product> validator)
    {
        _validator = validator;
    }

    // POST: api/products
    [HttpPost]
    public IActionResult CreateProduct([FromBody] Product product)
    {
        var validationResult = _validator.Validate(product);

        if (!validationResult.IsValid)
        {
            return BadRequest(validationResult.Errors.Select(e => e.ErrorMessage));
        }

        // The rest of your code for creating the product...

        return Ok("Product created successfully.");
    }
}

上面的示例中，CreateProduct 操作方法接收一个 Product 对象，并使用 ProductValidator 进行验证。如果验证失败，将返回包含错误信息的 BadRequest 响应；否则，将继续执行创建产品的逻辑。

五、总结

在ASP.NET Core Web API的创建和配置过程中，我们首先使用.NET CLI创建项目，并了解了项目结构。了解Web API路由的基本概念是关键，可以通过特性路由或全局路由配置来定义API端点。创建数据模型是构建API的基础，可以通过数据注解或Fluent Validation来进行验证。此外，使用DTOs（数据传输对象）有助于有效地在客户端和服务端之间传输数据，并控制传输的数据内容。最后，实现了简单的控制器类，演示了创建、读取、更新和删除资源的操作。总体而言，通过这个流程，我们搭建了一个基本的ASP.NET Core Web API，涉及了路由、数据模型、验证和数据传输等关键概念。这为进一步的开发和扩展提供了基础。