Volba mezi rozhraními API založenými na kontroleru a minimálními rozhraními API

  • Článek

Poznámka:

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Upozorňující

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v tématu .NET a .NET Core Zásady podpory. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Důležité

Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

ASP.NET Core podporuje dva přístupy k vytváření rozhraní API: přístup založený na kontroleru a minimální rozhraní API. Kontrolery v projektu rozhraní API jsou třídy, které jsou odvozeny od ControllerBase. Minimální rozhraní API definují koncové body s logickými obslužnými rutinami v lambda nebo metodách. Tento článek popisuje rozdíly mezi dvěma přístupy.

Návrh minimálních rozhraní API ve výchozím nastavení skryje třídu hostitele a zaměřuje se na konfiguraci a rozšiřitelnost prostřednictvím rozšiřujících metod, které používají funkce jako výrazy lambda. Kontrolery jsou třídy, které mohou přijímat závislosti prostřednictvím injektáže konstruktoru nebo injektáže vlastností a obecně se řídí objektově orientovanými vzory. Minimální rozhraní API podporují injektáž závislostí prostřednictvím jiných přístupů, jako je přístup k poskytovateli služeb.

Tady je ukázkový kód pro rozhraní API na základě kontrolerů:


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();
    }
}

Následující kód poskytuje stejné funkce v minimálním projektu rozhraní API. Všimněte si, že minimální přístup rozhraní API zahrnuje zahrnutí souvisejícího kódu do výrazů lambda.


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();
    }
}

Oba projekty rozhraní API odkazují na následující třídu:

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; }
}

Minimální rozhraní API mají mnoho stejných funkcí jako rozhraní API založená na kontroleru. Podporují konfiguraci a přizpůsobení potřebné ke škálování na více rozhraní API, zpracování složitých tras, použití autorizačních pravidel a řízení obsahu odpovědí rozhraní API. U rozhraní API založených na kontroleru je k dispozici několik možností, které ještě nejsou podporovány nebo implementovány minimálními rozhraními API. Tady jsou některé z nich:

Viz také

ASP.NET Core podporuje dva přístupy k vytváření rozhraní API: přístup založený na kontroleru a minimální rozhraní API. Kontrolery v projektu rozhraní API jsou třídy, které jsou odvozeny od ControllerBase. Minimální rozhraní API definují koncové body s logickými obslužnými rutinami v lambda nebo metodách. Tento článek popisuje rozdíly mezi dvěma přístupy.

Návrh minimálních rozhraní API ve výchozím nastavení skryje třídu hostitele a zaměřuje se na konfiguraci a rozšiřitelnost prostřednictvím rozšiřujících metod, které používají funkce jako výrazy lambda. Kontrolery jsou třídy, které mohou přijímat závislosti prostřednictvím injektáže konstruktoru nebo injektáže vlastností a obecně se řídí objektově orientovanými vzory. Minimální rozhraní API podporují injektáž závislostí prostřednictvím jiných přístupů, jako je přístup k poskytovateli služeb.

Tady je ukázkový kód pro rozhraní API na základě kontrolerů:


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();
    }
}

Následující kód poskytuje stejné funkce v minimálním projektu rozhraní API. Všimněte si, že minimální přístup rozhraní API zahrnuje zahrnutí souvisejícího kódu do výrazů lambda.


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();
    }
}

Oba projekty rozhraní API odkazují na následující třídu:

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; }
}

Minimální rozhraní API mají mnoho stejných funkcí jako rozhraní API založená na kontroleru. Podporují konfiguraci a přizpůsobení potřebné ke škálování na více rozhraní API, zpracování složitých tras, použití autorizačních pravidel a řízení obsahu odpovědí rozhraní API. U rozhraní API založených na kontroleru je k dispozici několik možností, které ještě nejsou podporovány nebo implementovány minimálními rozhraními API. Tady jsou některé z nich:

Viz také