ASP.NET Core中的Web API是什么？如何创建？-C#.Net教程-PHP中文网

ASP.NET Core Web API 是用于构建 RESTful 服务的框架，通过创建项目、定义模型与控制器、配置路由及中间件实现 HTTP 端点，支持身份验证（如 JWT）、异常处理、API 版本控制、单元测试和 Swagger 文档集成。

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 提供了多种身份验证方案，包括：

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<IEnumerable<Product>> Get()
{
    return _products;
}

登录后复制

如何处理 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<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 提供了多种版本控制方法：

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<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 文档文件的路径。