使用 ASP.NET Core 创建 RESTful API

RESTful API（Representational State Transfer）是一种设计风格，用于在客户端和服务器之间传递数据。ASP.NET Core 提供了一个简洁而强大的框架来构建 RESTful API，能够快速开发和部署高性能的 Web API 应用。

1. 创建 ASP.NET Core 项目

首先，确保你已经安装了最新版本的 .NET SDK。打开终端或命令行工具，使用以下命令创建新的 ASP.NET Core Web API 项目：

dotnet new webapi -n MyRestfulApi
cd MyRestfulApi

该命令会创建一个名为 MyRestfulApi 的项目，其中包含基本的 Web API 模板结构。

2. 配置 Startup.cs

在 ASP.NET Core 中，Startup.cs 是应用的核心配置文件，负责配置请求管道和服务。

在 Startup.cs 中，你会看到 ConfigureServices 方法和 Configure 方法。ConfigureServices 用于注册应用的服务，例如依赖注入、数据库上下文等；Configure 用于设置中间件，例如路由、认证等。

public class Startup
{
    // 该方法用于注册应用服务，包括控制器、Swagger等
    public void ConfigureServices(IServiceCollection services)
    {
        // 注册控制器服务，支持基于MVC的Web API开发
        services.AddControllers();
        
        // 注册Swagger生成器，用于生成API文档
        services.AddSwaggerGen();
    }

    // 该方法配置HTTP请求管道中的中间件
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        // 如果是开发环境，启用开发者异常页面，方便调试
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        // 启用Swagger中间件来生成Swagger文档
        app.UseSwagger();

        // 启用SwaggerUI，为Swagger文档提供UI界面，方便测试API
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        });

        // 启用路由中间件，支持终端路由映射
        app.UseRouting();

        // 启用终端中间件，将控制器映射到路由
        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

在上面的代码中，我们通过 services.AddControllers() 方法添加了控制器支持。这是创建 RESTful API 的基础。

3. 创建控制器

接下来，我们创建一个简单的控制器来处理 HTTP 请求。在 Controllers 文件夹下添加一个新的控制器文件 ProductsController.cs。

[ApiController] // 指定该类是API控制器，自动启用模型验证和错误处理
[Route("api/[controller]")] // 为控制器定义路由，支持基于控制器名的URL
public class ProductsController : ControllerBase
{
    // 模拟的产品数据列表
    private static readonly List<Product> Products = new List<Product>
    {
        new Product { Id = 1, Name = "Product1", Price = 10.0M },
        new Product { Id = 2, Name = "Product2", Price = 20.0M }
    };

    // 获取所有产品
    [HttpGet] // 处理GET请求，返回产品列表
    public IEnumerable<Product> GetAll()
    {
        return Products; // 返回产品数据
    }

    // 根据ID获取产品
    [HttpGet("{id}")] // 处理GET请求，接受URL中的ID参数
    public ActionResult<Product> GetById(int id)
    {
        // 查找指定ID的产品
        var product = Products.FirstOrDefault(p => p.Id == id);
        
        // 如果未找到产品，返回404 Not Found
        if (product == null)
        {
            return NotFound();
        }
        
        // 返回找到的产品数据
        return product;
    }

    // 创建新产品
    [HttpPost] // 处理POST请求，接受请求体中的产品数据
    public ActionResult<Product> Create(Product product)
    {
        // 生成新产品的ID
        product.Id = Products.Max(p => p.Id) + 1;
        
        // 将新产品添加到产品列表中
        Products.Add(product);
        
        // 返回201 Created状态码，并在响应中包含新创建的产品
        return CreatedAtAction(nameof(GetById), new { id = product.Id }, product);
    }

    // 更新产品信息
    [HttpPut("{id}")] // 处理PUT请求，接受URL中的ID参数和请求体中的更新数据
    public IActionResult Update(int id, Product updatedProduct)
    {
        // 查找指定ID的产品
        var product = Products.FirstOrDefault(p => p.Id == id);
        
        // 如果未找到产品，返回404 Not Found
        if (product == null)
        {
            return NotFound();
        }

        // 更新产品的名称和价格
        product.Name = updatedProduct.Name;
        product.Price = updatedProduct.Price;

        // 返回204 No Content状态码，表示更新成功但不返回数据
        return NoContent();
    }

    // 删除指定ID的产品
    [HttpDelete("{id}")] // 处理DELETE请求，接受URL中的ID参数
    public IActionResult Delete(int id)
    {
        // 查找指定ID的产品
        var product = Products.FirstOrDefault(p => p.Id == id);
        
        // 如果未找到产品，返回404 Not Found
        if (product == null)
        {
            return NotFound();
        }

        // 从产品列表中移除该产品
        Products.Remove(product);
        
        // 返回204 No Content状态码，表示删除成功
        return NoContent();
    }
}

4. 定义模型

我们需要定义 Product 模型来表示 API 中使用的产品对象。在 Models 文件夹下添加一个新的类 Product.cs。

// 定义产品模型类，用于表示API中传输的产品数据
public class Product
{
    public int Id { get; set; } // 产品的唯一标识符
    public string Name { get; set; } // 产品名称
    public decimal Price { get; set; } // 产品价格
}

5. 测试 API

启动应用后，你可以通过 Postman 或浏览器来测试 API：

• GET /api/products： 返回所有产品
• GET /api/products/{id}： 根据 ID 返回产品
• POST /api/products： 创建新产品
• PUT /api/products/{id}： 更新产品信息
• DELETE /api/products/{id}： 删除指定产品

6. 使用 Swagger 进行 API 文档生成

为了简化 API 文档的生成和测试，ASP.NET Core 提供了对 Swagger 的内置支持。你可以通过安装 Swashbuckle.AspNetCore NuGet 包来轻松集成 Swagger。

安装依赖项：

dotnet add package Swashbuckle.AspNetCore

在 Startup.cs 中注册 Swagger 服务：

public class Startup
{
    // 配置服务注册的方法
    public void ConfigureServices(IServiceCollection services)
    {
        // 注册控制器服务，支持基于MVC的Web API开发
        services.AddControllers();
        
        // 注册Swagger生成器服务，用于生成API文档
        services.AddSwaggerGen();
    }

    // 配置HTTP请求管道的方法
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        // 如果当前环境是开发环境，启用开发者异常页面以方便调试
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        // 启用Swagger中间件，用于生成API的Swagger文档
        app.UseSwagger();

        // 启用Swagger UI中间件，提供用户界面来查看和测试API的文档
        app.UseSwaggerUI(c =>
        {
            // 配置Swagger端点，指定Swagger JSON的URL路径和API版本标题
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        });

        // 启用路由中间件，解析传入的HTTP请求并将其路由到适当的终端点
        app.UseRouting();

        // 配置终端点映射，将控制器动作映射到路由
        app.UseEndpoints(endpoints =>
        {
            // 映射控制器终端点，使控制器能够处理请求
            endpoints.MapControllers();
        });
    }
}

运行应用后，访问 http://localhost:{port}/swagger 就可以看到自动生成的 API 文档并进行测试了。

7. 小结

通过本文的介绍，你已经学会了如何使用 ASP.NET Core 创建一个简单的 RESTful API。从创建控制器到使用 Swagger 生成文档，ASP.NET Core 提供了全面而简洁的工具，使得构建 RESTful 服务变得更加高效和便捷。