Udostępnij za pośrednictwem


Wybieranie między interfejsami API opartymi na kontrolerze i minimalnymi interfejsami API

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz .NET i .NET Core Support Policy (Zasady obsługi platformy .NET Core). Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

ASP.NET Core obsługuje dwa podejścia do tworzenia interfejsów API: podejście oparte na kontrolerze i minimalne interfejsy API. Kontrolery w projekcie interfejsu API to klasy pochodzące z ControllerBaseklasy . Minimalne interfejsy API definiują punkty końcowe z logicznymi procedurami obsługi w wyrażeniach lambd lub metodach. W tym artykule przedstawiono różnice między dwoma podejściami.

Projekt minimalnych interfejsów API domyślnie ukrywa klasę hosta i koncentruje się na konfiguracji i rozszerzalności za pomocą metod rozszerzeń, które przyjmują funkcje jako wyrażenia lambda. Kontrolery to klasy, które mogą pobierać zależności za pośrednictwem wstrzykiwania konstruktora lub iniekcji właściwości, i zwykle podążać za wzorcami obiektowymi. Minimalne interfejsy API obsługują wstrzykiwanie zależności za pośrednictwem innych metod, takich jak uzyskiwanie dostępu do dostawcy usług.

Oto przykładowy kod interfejsu API oparty na kontrolerach:


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

Poniższy kod zapewnia te same funkcje w minimalnym projekcie interfejsu API. Zwróć uwagę, że minimalne podejście interfejsu API obejmuje uwzględnienie powiązanego kodu w wyrażeniach 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 interfejsu API odwołują się do następującej klasy:

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

Minimalne interfejsy API mają wiele takich samych możliwości jak interfejsy API oparte na kontrolerach. Obsługują one konfigurację i dostosowywanie wymagane do skalowania do wielu interfejsów API, obsługę złożonych tras, stosowanie reguł autoryzacji i kontrolowanie zawartości odpowiedzi interfejsu API. Istnieje kilka funkcji dostępnych w przypadku interfejsów API opartych na kontrolerach, które nie są jeszcze obsługiwane lub implementowane przez minimalne interfejsy API. Są to:

  • Brak wbudowanej obsługi powiązania modelu (IModelBinderProvider, IModelBinder). Obsługę można dodać za pomocą podkładki powiązania niestandardowego.
  • Brak wbudowanej obsługi weryfikacji (IModelValidator).
  • Brak obsługi części aplikacji ani modelu aplikacji. Nie ma możliwości stosowania ani tworzenia własnych konwencji.
  • Brak wbudowanej obsługi renderowania widoków. Zalecamy używanie Razor stron do renderowania widoków.
  • Brak obsługi kodu JsonPatch
  • Brak obsługi OData

Zobacz też

ASP.NET Core obsługuje dwa podejścia do tworzenia interfejsów API: podejście oparte na kontrolerze i minimalne interfejsy API. Kontrolery w projekcie interfejsu API to klasy pochodzące z ControllerBaseklasy . Minimalne interfejsy API definiują punkty końcowe z logicznymi procedurami obsługi w wyrażeniach lambd lub metodach. W tym artykule przedstawiono różnice między dwoma podejściami.

Projekt minimalnych interfejsów API domyślnie ukrywa klasę hosta i koncentruje się na konfiguracji i rozszerzalności za pomocą metod rozszerzeń, które przyjmują funkcje jako wyrażenia lambda. Kontrolery to klasy, które mogą pobierać zależności za pośrednictwem wstrzykiwania konstruktora lub iniekcji właściwości, i zwykle podążać za wzorcami obiektowymi. Minimalne interfejsy API obsługują wstrzykiwanie zależności za pośrednictwem innych metod, takich jak uzyskiwanie dostępu do dostawcy usług.

Oto przykładowy kod interfejsu API oparty na kontrolerach:


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

Poniższy kod zapewnia te same funkcje w minimalnym projekcie interfejsu API. Zwróć uwagę, że minimalne podejście interfejsu API obejmuje uwzględnienie powiązanego kodu w wyrażeniach 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 interfejsu API odwołują się do następującej klasy:

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

Minimalne interfejsy API mają wiele takich samych możliwości jak interfejsy API oparte na kontrolerach. Obsługują one konfigurację i dostosowywanie wymagane do skalowania do wielu interfejsów API, obsługę złożonych tras, stosowanie reguł autoryzacji i kontrolowanie zawartości odpowiedzi interfejsu API. Istnieje kilka funkcji dostępnych w przypadku interfejsów API opartych na kontrolerach, które nie są jeszcze obsługiwane lub implementowane przez minimalne interfejsy API. Są to:

  • Brak wbudowanej obsługi powiązania modelu (IModelBinderProvider, IModelBinder). Obsługę można dodać za pomocą podkładki powiązania niestandardowego.
  • Brak obsługi powiązań z formularzy. Obejmuje to powiązanie IFormFile.
  • Brak wbudowanej obsługi weryfikacji (IModelValidator).
  • Brak obsługi części aplikacji ani modelu aplikacji. Nie ma możliwości stosowania ani tworzenia własnych konwencji.
  • Brak wbudowanej obsługi renderowania widoków. Zalecamy używanie Razor stron do renderowania widoków.
  • Brak obsługi kodu JsonPatch
  • Brak obsługi OData

Zobacz też