ASP.NET Core Web API 是用于构建 RESTful 服务的框架，通过创建项目、定义模型与控制器、配置路由及中间件实现 HTTP 端点，支持身份验证（如 JWT）、异常处理、API 版本控制、单元测试和 Swagger 文档集成。
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_products = new List { new Product { Id = 1, Name = "Product 1", Price = 10.00m }, new Product { Id = 2, Name = "Product 2", Price = 20.00m } }; [HttpGet] public ActionResult Get(int id) { var product = _products.FirstOrDefault(p => p.Id == id); if (product == null) { return NotFound(); } return product; } [HttpPost] public ActionResult 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
允许你返回不同类型的结果，例如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:
访问，其中/swagger
是你的应用程序监听的端口。
如何处理 Web API 中的身份验证和授权？
身份验证和授权是 Web API 安全的关键部分。ASP.NET Core 提供了多种身份验证方案，包括：
-
JWT (JSON Web Tokens): 一种常用的基于令牌的身份验证方法。客户端在登录后获得 JWT，并在后续请求中将其包含在
Authorization
头部中。服务器验证令牌的有效性，并根据令牌中的声明授予访问权限。 - Cookie 认证: 适用于基于浏览器的应用程序，服务器在用户登录后设置 Cookie，客户端在后续请求中自动发送 Cookie。
- OAuth 2.0: 一种授权框架，允许第三方应用程序代表用户访问 API。
- API 密钥: 一种简单的身份验证方法，客户端在请求中包含一个 API 密钥。
授权通常与身份验证结合使用。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
如何处理 Web API 中的错误和异常？
处理错误和异常对于构建健壮的 Web API 至关重要。ASP.NET Core 提供了多种处理错误的方法：
- 全局异常处理中间件： 你可以创建一个自定义中间件来捕获未处理的异常，并返回一个统一的错误响应。
- 异常过滤器： 你可以创建异常过滤器来处理特定类型的异常。
-
IActionResult
返回类型： 你可以使用IActionResult
返回类型来返回不同类型的错误响应，例如BadRequest
,NotFound
,InternalServerError
。 -
ProblemDetails
类型： ASP.NET Core 3.1 及更高版本引入了ProblemDetails
类型，用于返回标准化的错误响应。
例如，创建一个全局异常处理中间件：
public class ExceptionMiddleware
{
private readonly RequestDelegate _next;
private readonly ILogger _logger;
public ExceptionMiddleware(RequestDelegate next, ILogger 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();
}
//Program.cs (.NET 6+)
app.UseMiddleware(); 如何进行 Web API 的版本控制？
Web API 的版本控制允许你在不破坏现有客户端的情况下引入新的功能或更改。ASP.NET Core 提供了多种版本控制方法：
-
URI 版本控制： 在 URI 中包含版本号，例如
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 -
安装 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(result.Result); } [Fact] public void Get_ReturnsAllProducts() { // Arrange var mockLogger = new Mock - 使用
[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:
访问，其中/swagger
是你的应用程序监听的端口。 -
添加 XML 注释：
你可以添加 XML 注释到你的控制器和模型类中，Swagger 会自动生成 API 文档。你需要配置项目以生成 XML 文档文件，并在
AddSwaggerGen
方法中指定 XML 文档文件的路径。
这些是创建和使用 ASP.NET Core Web API 的一些关键方面。当然，还有很多更高级的主题，例如依赖注入、配置、日志记录和部署。
