10.2 Web API开发

概述

Web API是现代应用程序开发中不可或缺的一部分，它允许不同系统之间通过HTTP协议进行通信。在ASP.NET Core中，Web API的开发变得简单而高效。本节将介绍如何使用ASP.NET Core构建RESTful风格的Web API。

创建Web API项目

使用Visual Studio创建

  1. 打开Visual Studio
  2. 选择"创建新项目"
  3. 选择"ASP.NET Core Web API"模板
  4. 配置项目名称和位置
  5. 选择.NET版本（推荐最新稳定版）
  6. 确保勾选"启用OpenAPI支持"（Swagger）

使用命令行创建

dotnet new webapi -n MyWebApi
cd MyWebApi

控制器(Controllers)

基本控制器结构

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    public IEnumerable<Product> Get()
    {
        // 返回产品列表
    }
    
    [HttpGet("{id}")]
    public ActionResult<Product> Get(int id)
    {
        // 根据ID返回单个产品
    }
}

常用HTTP方法注解

  • [HttpGet] - 获取资源
  • [HttpPost] - 创建资源
  • [HttpPut] - 更新资源
  • [HttpDelete] - 删除资源
  • [HttpPatch] - 部分更新资源

路由(Routing)

特性路由

[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet("all")]  // 对应/api/products/all
    public IActionResult GetAll() { ... }
}

路由参数

[HttpGet("{id:int}")]  // 约束id必须为整数
public IActionResult GetById(int id) { ... }

模型绑定与验证

模型绑定

[HttpPost]
public IActionResult Create([FromBody] Product product)
{
    // product会自动从请求体反序列化
}

数据验证

public class Product
{
    [Required]
    public string Name { get; set; }
    
    [Range(0, 1000)]
    public decimal Price { get; set; }
}

[HttpPost]
public IActionResult Create([FromBody] Product product)
{
    if (!ModelState.IsValid)
    {
        return BadRequest(ModelState);
    }
    // 处理有效数据
}

返回结果

常用返回类型

  • Ok() - 200 OK
  • Created() - 201 Created
  • NoContent() - 204 No Content
  • BadRequest() - 400 Bad Request
  • NotFound() - 404 Not Found

示例

[HttpGet("{id}")]
public ActionResult<Product> GetById(int id)
{
    var product = _repository.GetProduct(id);
    if (product == null)
    {
        return NotFound();
    }
    return Ok(product);
}

依赖注入

服务注册

public void ConfigureServices(IServiceCollection services)
{
    services.AddScoped<IProductRepository, ProductRepository>();
}

控制器中使用

public class ProductsController : ControllerBase
{
    private readonly IProductRepository _repository;
    
    public ProductsController(IProductRepository repository)
    {
        _repository = repository;
    }
}

中间件与管道

常用中间件

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseSwagger();
        app.UseSwaggerUI();
    }
    
    app.UseHttpsRedirection();
    app.UseRouting();
    app.UseAuthorization();
    app.UseEndpoints(endpoints => endpoints.MapControllers());
}

版本控制

使用Microsoft.AspNetCore.Mvc.Versioning

  1. 安装NuGet包
dotnet add package Microsoft.AspNetCore.Mvc.Versioning
  1. 配置服务
services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
});
  1. 版本化控制器
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ProductsController : ControllerBase { ... }

安全考虑

认证与授权

[Authorize]
[ApiController]
public class SecureController : ControllerBase { ... }

// 特定角色
[Authorize(Roles = "Admin")]
public class AdminController : ControllerBase { ... }

CORS配置

services.AddCors(options =>
{
    options.AddPolicy("AllowSpecificOrigin",
        builder => builder.WithOrigins("http://example.com")
                         .AllowAnyMethod()
                         .AllowAnyHeader());
});

app.UseCors("AllowSpecificOrigin");

测试Web API

使用Swagger/OpenAPI

ASP.NET Core默认集成了Swagger，访问/swagger即可查看和测试API。

使用Postman

  1. 创建请求集合
  2. 设置环境变量
  3. 编写测试脚本

单元测试

[Fact]
public async Task Get_ReturnsListOfProducts()
{
    // 安排
    var mockRepo = new Mock<IProductRepository>();
    mockRepo.Setup(repo => repo.GetAll())
           .Returns(GetTestProducts());
    var controller = new ProductsController(mockRepo.Object);
    
    // 执行
    var result = await controller.Get();
    
    // 断言
    var actionResult = Assert.IsType<ActionResult<IEnumerable<Product>>>(result);
    var returnValue = Assert.IsType<List<Product>>(actionResult.Value);
    Assert.Equal(2, returnValue.Count);
}

性能优化

响应缓存

[ResponseCache(Duration = 60)]
[HttpGet]
public IEnumerable<Product> Get()
{
    // 响应将被缓存60秒
}

压缩响应

services.AddResponseCompression(options =>
{
    options.Providers.Add<GzipCompressionProvider>();
    options.EnableForHttps = true;
});

部署考虑

生产环境配置

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>()
                      .UseUrls("http://*:5000");
        });

Docker支持

FROM mcr.microsoft.com/dotnet/aspnet:5.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:5.0 AS build
WORKDIR /src
COPY ["MyWebApi.csproj", "."]
RUN dotnet restore "MyWebApi.csproj"
COPY . .
RUN dotnet build "MyWebApi.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "MyWebApi.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MyWebApi.dll"]

总结

ASP.NET Core提供了强大而灵活的工具来构建现代Web API。通过遵循RESTful原则和利用框架提供的功能，开发者可以创建高性能、可维护和可扩展的API服务。

Last Updated::