API 概述

2025-08-28

注意

此版本不是本文的最新版本。有关当前版本，请参阅本文的 .NET 9 版本。

警告

此版本的 ASP.NET Core 不再受支持。有关详细信息，请参阅 .NET 和 .NET Core 支持策略。有关当前版本，请参阅本文的 .NET 9 版本。

重要

此信息与预发布产品相关，相应产品在商业发布之前可能会进行重大修改。 Microsoft 对此处提供的信息不提供任何明示或暗示的保证。

有关当前版本，请参阅本文的 .NET 9 版本。

ASP.NET Core 提供了两种生成 HTTP API 的方法： 最小 API 和基于控制器的 API。 对于新项目，我们建议使用最小 API ，因为它们提供了简化的高性能方法来生成具有最少代码和配置的 API。

最小 API - 建议用于新项目

建议使用最小 API 通过 ASP.NET Core 生成快速 HTTP API。它们允许你使用最少的代码和配置生成正常运行 REST 的终结点。通过流畅地声明 API 路由和作来跳过传统基架并避免不必要的控制器。

下面是在 Web 应用的根目录中创建 API 的简单示例：

var app = WebApplication.Create(args);

app.MapGet("/", () => "Hello World!");

app.Run();

大多数 API 接受参数作为路由的一部分：

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/users/{userId}/books/{bookId}", 
    (int userId, int bookId) => $"The user id is {userId} and book id is {bookId}");

app.Run();

最小 API 支持缩放到多个 API、处理复杂路由、应用授权规则和控制 API 响应内容所需的配置和自定义。

最小 API 入门

教程：使用 ASP.NET Core 创建最小 API
快速参考：最小 API 快速参考
示例：有关包含代码示例的常见方案的完整列表，请参阅 “最小 API”快速参考

基于控制器的 API - 替代方法

ASP.NET Core 还支持基于控制器的方法，其中控制器是派生自 ControllerBase的类。此方法遵循传统的面向对象的模式，并可能首选：

具有复杂业务逻辑的大型应用程序
熟悉 MVC 模式的 Teams
需要特定 MVC 功能的应用程序

下面是基于控制器的 API 的示例代码：


namespace APIWithControllers;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.Services.AddControllers();
        var app = builder.Build();

        app.UseHttpsRedirection();

        app.MapControllers();

        app.Run();
    }
}

using Microsoft.AspNetCore.Mvc;

namespace APIWithControllers.Controllers;
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    private static readonly string[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };

    private readonly ILogger<WeatherForecastController> _logger;

    public WeatherForecastController(ILogger<WeatherForecastController> logger)
    {
        _logger = logger;
    }

    [HttpGet(Name = "GetWeatherForecast")]
    public IEnumerable<WeatherForecast> Get()
    {
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = Summaries[Random.Shared.Next(Summaries.Length)]
        })
        .ToArray();
    }
}

以下代码使用建议的最小 API 方法提供相同的功能：


namespace MinimalAPI;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        var app = builder.Build();

        app.UseHttpsRedirection();

        var summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        app.MapGet("/weatherforecast", (HttpContext httpContext) =>
        {
            var forecast = Enumerable.Range(1, 5).Select(index =>
                new WeatherForecast
                {
                    Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                    TemperatureC = Random.Shared.Next(-20, 55),
                    Summary = summaries[Random.Shared.Next(summaries.Length)]
                })
                .ToArray();
            return forecast;
        });

        app.Run();
    }
}

两个 API 项目都引用以下类：

namespace APIWithControllers;

public class WeatherForecast
{
    public DateOnly Date { get; set; }

    public int TemperatureC { get; set; }

    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

    public string? Summary { get; set; }
}

在方法之间进行选择

从新项目的最小 API 开始。他们提供：

更简单的语法 - 更少的样板代码
更好的性能 - 与控制器相比降低了开销
简化测试 - 简化单元和集成测试
新式方法 - 利用最新的 .NET 功能

如果需要，请考虑基于控制器的 API：

模型绑定扩展性（IModelBinderProvider， IModelBinder）
高级验证功能（IModelValidator）
应用程序部件或应用程序模型
JsonPatch 支持
OData 支持

大多数这些功能都可以使用自定义解决方案在最小 API 中实现，但控制器现成提供这些功能。

另请参阅

教程：使用 ASP.NET Core 创建最小 API - 最小 API 教程
最小 API 快速参考 - 最小 API 快速参考
使用 ASP.NET 核心创建 Web API - 基于控制器的 API 概述
教程：使用 ASP.NET 核心创建基于控制器的 Web API - 基于控制器的 API 教程

最小 API - 建议用于新项目

建议使用最小 API 通过 ASP.NET Core 生成快速 HTTP API。它们允许你使用最少的代码和配置生成正常运行 REST 的终结点。

下面是一个简单的示例：

var app = WebApplication.Create(args);

app.MapGet("/", () => "Hello World!");

app.Run();

最小 API 入门

教程：使用 ASP.NET Core 创建最小 API
快速参考：最小 API 快速参考

基于控制器的 API - 替代方法

控制器是派生自 ControllerBase的类。此方法遵循传统的面向对象的模式。

下面是基于控制器的 API 的示例代码：


namespace APIWithControllers;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.Services.AddControllers();
        var app = builder.Build();

        app.UseHttpsRedirection();

        app.MapControllers();

        app.Run();
    }
}

using Microsoft.AspNetCore.Mvc;

namespace APIWithControllers.Controllers;
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    private static readonly string[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };

    private readonly ILogger<WeatherForecastController> _logger;

    public WeatherForecastController(ILogger<WeatherForecastController> logger)
    {
        _logger = logger;
    }

    [HttpGet(Name = "GetWeatherForecast")]
    public IEnumerable<WeatherForecast> Get()
    {
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = Summaries[Random.Shared.Next(Summaries.Length)]
        })
        .ToArray();
    }
}

以下代码使用建议的最小 API 方法提供相同的功能：


namespace MinimalAPI;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        var app = builder.Build();

        app.UseHttpsRedirection();

        var summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        app.MapGet("/weatherforecast", (HttpContext httpContext) =>
        {
            var forecast = Enumerable.Range(1, 5).Select(index =>
                new WeatherForecast
                {
                    Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                    TemperatureC = Random.Shared.Next(-20, 55),
                    Summary = summaries[Random.Shared.Next(summaries.Length)]
                })
                .ToArray();
            return forecast;
        });

        app.Run();
    }
}

两个 API 项目都引用以下类：

namespace APIWithControllers;

public class WeatherForecast
{
    public DateOnly Date { get; set; }

    public int TemperatureC { get; set; }

    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

    public string? Summary { get; set; }
}

在方法之间进行选择

从新项目的最小 API 开始。如果需要，请考虑基于控制器的 API：

模型绑定扩展性（IModelBinderProvider， IModelBinder）
表单绑定支持，包括 IFormFile
高级验证功能（IModelValidator）
应用程序部件或应用程序模型
JsonPatch 支持
OData 支持

另请参阅

教程：使用 ASP.NET Core 创建最小 API - 最小 API 教程
最小 API 快速参考 - 最小 API 快速参考
使用 ASP.NET 核心创建 Web API - 基于控制器的 API 概述
教程：使用 ASP.NET 核心创建基于控制器的 Web API - 基于控制器的 API 教程

反馈

此页面是否有帮助？

通过

API 概述

最小 API - 建议用于新项目

最小 API 入门

基于控制器的 API - 替代方法

在方法之间进行选择

另请参阅

最小 API - 建议用于新项目

最小 API 入门

基于控制器的 API - 替代方法

在方法之间进行选择

另请参阅

反馈

其他资源