ASP.NET Core中的Web API是什么？如何创建？

ASP.NET Core Web API 是一种用于构建基于 HTTP 的 RESTful 服务的框架。你可以用它创建可以通过 HTTP 请求访问的端点，并返回各种格式的数据，比如 JSON。创建过程简单来说就是新建项目，定义控制器和操作，配置路由，然后就可以运行了。

解决方案

创建 ASP.NET Core Web API 的步骤如下：

创建新的 ASP.NET Core Web API 项目：

使用 Visual Studio: 打开 Visual Studio，选择“创建新项目”，然后选择 "ASP.NET Core Web API"。 使用 .NET CLI: 在命令行中运行

dotnet new webapi -n MyWebApi

定义模型 (可选):

如果你的 API 需要处理复杂的数据，你需要定义模型类。例如，创建一个

Product

类：

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

创建控制器：

控制器负责处理传入的 HTTP 请求。创建一个新的控制器类，例如

ProductsController

，并继承自

ControllerBase

。

 using Microsoft.AspNetCore.Mvc;
 using System.Collections.Generic;
 using System.Linq;
 [ApiController]
 [Route("api/[controller]")]
 public class ProductsController : ControllerBase
 {
     private static readonly List<Product> _products = new List<Product>
     {
         new Product { Id = 1, Name = "Product 1", Price = 10.00m },
         new Product { Id = 2, Name = "Product 2", Price = 20.00m }
     };
     [HttpGet]
     public ActionResult<IEnumerable<Product>> Get()
     {
         return _products;
     }
     [HttpGet("{id}")]
     public ActionResult<Product> Get(int id)
     {
         var product = _products.FirstOrDefault(p => p.Id == id);
         if (product == null)
         {
             return NotFound();
         }
         return product;
     }
     [HttpPost]
     public ActionResult<Product> Post(Product product)
     {
         product.Id = _products.Count + 1;
         _products.Add(product);
         return CreatedAtAction(nameof(Get), new { id = product.Id }, product);
     }
     [HttpPut("{id}")]
     public IActionResult Put(int id, Product product)
     {
         if (id != product.Id)
         {
             return BadRequest();
         }
         var existingProduct = _products.FirstOrDefault(p => p.Id == id);
         if (existingProduct == null)
         {
             return NotFound();
         }
         existingProduct.Name = product.Name;
         existingProduct.Price = product.Price;
         return NoContent();
     }
     [HttpDelete("{id}")]
     public IActionResult Delete(int id)
     {
         var product = _products.FirstOrDefault(p => p.Id == id);
         if (product == null)
         {
             return NotFound();
         }
         _products.Remove(product);
         return NoContent();
     }
 }

[ApiController]

特性表明该类是一个 API 控制器。

[Route("api/[controller]")]

特性定义了路由模板，

[controller]

会被替换为控制器名称（不包括 "Controller" 后缀）。

[HttpGet]

,

[HttpPost]

,

[HttpPut]

,

[HttpDelete]

特性指定了 HTTP 方法。

ActionResult<T>

允许你返回不同类型的结果，例如

Ok

,

NotFound

,

BadRequest

。

配置服务 (Startup.cs 或 Program.cs):

在

Startup.cs

(或者 .NET 6+ 的

Program.cs

) 文件中，配置 MVC 服务。

 // Startup.cs (ConfigureServices 方法)
 public void ConfigureServices(IServiceCollection services)
 {
     services.AddControllers();
     services.AddSwaggerGen(c =>
     {
         c.SwaggerDoc("v1", new OpenApiInfo { Title = "MyWebApi", Version = "v1" });
     });
 }
 // Startup.cs (Configure 方法)
 public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
 {
     if (env.IsDevelopment())
     {
         app.UseDeveloperExceptionPage();
         app.UseSwagger();
         app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "MyWebApi v1"));
     }
     app.UseHttpsRedirection();
     app.UseRouting();
     app.UseAuthorization();
     app.UseEndpoints(endpoints =>
     {
         endpoints.MapControllers();
     });
 }
 //Program.cs (.NET 6+)
 var builder = WebApplication.CreateBuilder(args);
 // Add services to the container.
 builder.Services.AddControllers();
 // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
 builder.Services.AddEndpointsApiExplorer();
 builder.Services.AddSwaggerGen();
 var app = builder.Build();
 // Configure the HTTP request pipeline.
 if (app.Environment.IsDevelopment())
 {
     app.UseSwagger();
     app.UseSwaggerUI();
 }
 app.UseHttpsRedirection();
 app.UseAuthorization();
 app.MapControllers();
 app.Run();

AddControllers()

添加了 MVC 控制器。

AddSwaggerGen()

和相关的

UseSwagger

和

UseSwaggerUI

中间件用于生成和显示 API 文档。

运行应用程序：

运行你的 ASP.NET Core Web API 项目。你可以使用 Visual Studio 的调试器，或者在命令行中运行

dotnet run

。

测试 API：

你可以使用 Postman、curl 或 Swagger UI 来测试你的 API 端点。Swagger UI 通常在

https://localhost:<port>/swagger

访问，其中

<port>

是你的应用程序监听的端口。

如何处理 Web API 中的身份验证和授权？

身份验证和授权是 Web API 安全的关键部分。ASP.NET Core 提供了多种身份验证方案，包括：

Authorization

授权通常与身份验证结合使用。ASP.NET Core 提供了基于角色的授权和基于策略的授权。你可以使用

[Authorize]

例如，使用 JWT 身份验证：

安装 NuGet 包:

Install-Package Microsoft.AspNetCore.Authentication.JwtBearer

配置 JWT 身份验证 (Startup.cs 或 Program.cs):

//Startup.cs (ConfigureServices 方法)
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using System.Text;
public void ConfigureServices(IServiceCollection services)
{
    services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
        .AddJwtBearer(options =>
        {
            options.TokenValidationParameters = new TokenValidationParameters
            {
                ValidateIssuer = true,
                ValidateAudience = true,
                ValidateLifetime = true,
                ValidateIssuerSigningKey = true,
                ValidIssuer = Configuration["Jwt:Issuer"],
                ValidAudience = Configuration["Jwt:Audience"],
                IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(Configuration["Jwt:Key"]))
            };
        });
    services.AddControllers();
}
//Startup.cs (Configure 方法)
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
     app.UseAuthentication();
     app.UseAuthorization();
}
//Program.cs (.NET 6+)
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidAudience = builder.Configuration["Jwt:Audience"],
            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]))
        };
    });
// ...
app.UseAuthentication();
app.UseAuthorization();

生成 JWT 令牌：

你需要一个端点来生成 JWT 令牌，通常在登录时生成。

使用

[Authorize]

特性：

[Authorize]
[HttpGet]
public ActionResult<IEnumerable<Product>> Get()
{
    return _products;
}

如何处理 Web API 中的错误和异常？

处理错误和异常对于构建健壮的 Web API 至关重要。ASP.NET Core 提供了多种处理错误的方法：

IActionResult

IActionResult

BadRequest

NotFound

InternalServerError

ProblemDetails

ProblemDetails

例如，创建一个全局异常处理中间件：

public class ExceptionMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionMiddleware> _logger;
    public ExceptionMiddleware(RequestDelegate next, ILogger<ExceptionMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }
    public async Task InvokeAsync(HttpContext httpContext)
    {
        try
        {
            await _next(httpContext);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "An unhandled exception occurred.");
            httpContext.Response.StatusCode = 500;
            httpContext.Response.ContentType = "application/json";
            var problemDetails = new ProblemDetails
            {
                Status = 500,
                Title = "Internal Server Error",
                Detail = "An unexpected error occurred. Please try again later.",
                Instance = httpContext.Request.Path
            };
            await httpContext.Response.WriteAsync(JsonSerializer.Serialize(problemDetails));
        }
    }
}
//Startup.cs (Configure 方法)
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseMiddleware<ExceptionMiddleware>();
}
//Program.cs (.NET 6+)
app.UseMiddleware<ExceptionMiddleware>();

如何进行 Web API 的版本控制？

Web API 的版本控制允许你在不破坏现有客户端的情况下引入新的功能或更改。ASP.NET Core 提供了多种版本控制方法：

api/v1/products

api/products?api-version=1.0

Accept: application/json; version=1.0

Accept: application/vnd.myapi.v1+json

推荐使用 URI 版本控制或媒体类型版本控制。

例如，使用 URI 版本控制：

配置路由：

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        return new string[] { "value1 from version 1" };
    }
    [HttpGet]
    [MapToApiVersion("2.0")]
    public ActionResult<IEnumerable<string>> GetV2()
    {
        return new string[] { "value1 from version 2" };
    }
}

安装 NuGet 包:

Install-Package Microsoft.AspNetCore.Mvc.Versioning

配置 API 版本控制 (Startup.cs 或 Program.cs):

//Startup.cs (ConfigureServices 方法)
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Versioning;
public void ConfigureServices(IServiceCollection services)
{
    services.AddApiVersioning(o =>
    {
        o.AssumeDefaultVersionWhenUnspecified = true;
        o.DefaultApiVersion = new ApiVersion(1, 0);
        o.ReportApiVersions = true;
        o.ApiVersionReader = new UrlSegmentApiVersionReader();
    });
    services.AddControllers();
}
//Program.cs (.NET 6+)
builder.Services.AddApiVersioning(o =>
{
    o.AssumeDefaultVersionWhenUnspecified = true;
    o.DefaultApiVersion = new ApiVersion(1, 0);
    o.ReportApiVersions = true;
    o.ApiVersionReader = new UrlSegmentApiVersionReader();
});

如何对 Web API 进行单元测试？

单元测试是确保 Web API 代码质量的重要手段。你可以使用 MSTest, xUnit 或 NUnit 等单元测试框架来测试你的 API 控制器。

例如，使用 xUnit 进行单元测试：

创建测试项目：

创建一个新的 xUnit 测试项目，并添加对 Web API 项目的引用。

安装 NuGet 包:

Install-Package Microsoft.AspNetCore.Mvc.Core
Install-Package Microsoft.NET.Test.Sdk
Install-Package xunit
Install-Package xunit.runner.visualstudio
Install-Package Moq

编写测试用例：

using Xunit;
using MyWebApi.Controllers;
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using MyWebApi;
using Moq;
using Microsoft.Extensions.Logging;
public class ProductsControllerTests
{
    [Fact]
    public void Get_ReturnsOkResult()
    {
        // Arrange
        var mockLogger = new Mock<ILogger<ProductsController>>();
        var controller = new ProductsController(mockLogger.Object);
        // Act
        var result = controller.Get();
        // Assert
        Assert.IsType<OkObjectResult>(result.Result);
    }
    [Fact]
    public void Get_ReturnsAllProducts()
    {
        // Arrange
        var mockLogger = new Mock<ILogger<ProductsController>>();
        var controller = new ProductsController(mockLogger.Object);
        // Act
        var result = controller.Get() as ActionResult<IEnumerable<Product>>;
        var okResult = result.Result as OkObjectResult;
        // Assert
        var products = Assert.IsType<List<Product>>(okResult.Value);
        Assert.Equal(2, products.Count);
    }
}

使用

[Fact]

特性标记测试方法。 使用

Assert

类中的方法来验证测试结果。 使用 Moq 等模拟框架来模拟依赖项。

如何使用 Swagger/OpenAPI 来记录 Web API？

Swagger/OpenAPI 是一种用于描述 RESTful API 的标准。你可以使用 Swagger UI 来浏览和测试你的 API。

安装 NuGet 包:

Install-Package Swashbuckle.AspNetCore

配置 Swagger (Startup.cs 或 Program.cs):

//Startup.cs (ConfigureServices 方法)
using Microsoft.OpenApi.Models;
public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "MyWebApi", Version = "v1" });
    });
    services.AddControllers();
}
//Startup.cs (Configure 方法)
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseSwagger();
        app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "MyWebApi v1"));
    }
}
//Program.cs (.NET 6+)
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "MyWebApi", Version = "v1" });
});
// ...
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "MyWebApi v1"));
}

运行应用程序：

Swagger UI 通常在

https://localhost:<port>/swagger

访问，其中

<port>

是你的应用程序监听的端口。

添加 XML 注释：

你可以添加 XML 注释到你的控制器和模型类中，Swagger 会自动生成 API 文档。你需要配置项目以生成 XML 文档文件，并在

AddSwaggerGen

方法中指定 XML 文档文件的路径。

这些是创建和使用 ASP.NET Core Web API 的一些关键方面。当然，还有很多更高级的主题，例如依赖注入、配置、日志记录和部署。