API 概觀

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 模式的小組
• 需要特定 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 支援

這些功能大部分都可以在 Minimal API 中實作，並具有自訂解決方案，但控制器會提供開箱即用的功能。

另請參閱

• 教學課程：使用 ASP.NET Core 建立最小 API - 最小 API 教學課程
• 最小 API 快速參考 - 最小 API 快速參考
• 使用 ASP.NET Core 建立 Web API - 控制器型 API 概觀
• 教學課程：使用 ASP.NET Core 建立控制器型 Web API - 控制器型 API 教學課程