ASP.NET Core Minimal APIs 2026 완벽 가이드: 아키텍처, 성능 최적화, 면접 대비

var builder = WebApplication.CreateBuilder(args);

// 의존성 주입을 위한 서비스 등록
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.AddScoped<IProductRepository, ProductRepository>();

var app = builder.Build();

// 미들웨어 파이프라인 설정
app.UseExceptionHandler("/error");
app.UseHttpsRedirection();
app.UseAuthorization();

// Minimal API 엔드포인트 정의
app.MapGet("/products", async (IProductRepository repo) =>
    Results.Ok(await repo.GetAllAsync()));

app.MapGet("/products/{id:int}", async (int id, IProductRepository repo) =>
    await repo.GetByIdAsync(id) is Product product
        ? Results.Ok(product)
        : Results.NotFound());

app.Run();

public static class ProductEndpoints
{
    public static void MapProductEndpoints(this WebApplication app)
    {
        var group = app.MapGroup("/api/products")
            .WithTags("Products")
            .RequireAuthorization();

        group.MapGet("/", GetAllProducts);
        group.MapGet("/{id:int}", GetProductById);
        group.MapPost("/", CreateProduct)
            .Accepts<CreateProductRequest>("application/json")
            .Produces<Product>(StatusCodes.Status201Created);
        group.MapPut("/{id:int}", UpdateProduct);
        group.MapDelete("/{id:int}", DeleteProduct)
            .RequireAuthorization("AdminOnly");
    }

    private static async Task<IResult> GetAllProducts(
        IProductRepository repo,
        CancellationToken ct)
    {
        var products = await repo.GetAllAsync(ct);
        return Results.Ok(products);
    }

    private static async Task<IResult> GetProductById(
        int id,
        IProductRepository repo,
        CancellationToken ct)
    {
        var product = await repo.GetByIdAsync(id, ct);
        return product is not null
            ? Results.Ok(product)
            : Results.NotFound();
    }

    private static async Task<IResult> CreateProduct(
        CreateProductRequest request,
        IProductRepository repo,
        CancellationToken ct)
    {
        var product = await repo.CreateAsync(request, ct);
        return Results.Created($"/api/products/{product.Id}", product);
    }
}

// 비동기 스트리밍을 통한 대용량 데이터 효율적 처리
app.MapGet("/products/stream", async (IProductRepository repo) =>
{
    async IAsyncEnumerable<Product> StreamProducts()
    {
        await foreach (var product in repo.GetAllAsyncStream())
        {
            yield return product;
        }
    }
    return Results.Ok(StreamProducts());
});

// 응답 캐싱 활용
builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(builder => builder.Expire(TimeSpan.FromMinutes(5)));
    options.AddPolicy("ProductCache", builder =>
        builder.Expire(TimeSpan.FromMinutes(10))
               .Tag("products"));
});

app.MapGet("/products", async (IProductRepository repo) =>
    Results.Ok(await repo.GetAllAsync()))
    .CacheOutput("ProductCache");

// 캐시 무효화
app.MapPost("/products", async (
    CreateProductRequest request,
    IProductRepository repo,
    IOutputCacheStore cache) =>
{
    var product = await repo.CreateAsync(request);
    await cache.EvictByTagAsync("products", default);
    return Results.Created($"/api/products/{product.Id}", product);
});

// FluentValidation 통합
builder.Services.AddScoped<IValidator<CreateProductRequest>, CreateProductValidator>();

public class CreateProductValidator : AbstractValidator<CreateProductRequest>
{
    public CreateProductValidator()
    {
        RuleFor(x => x.Name)
            .NotEmpty().WithMessage("상품명은 필수입니다")
            .MaximumLength(100).WithMessage("상품명은 100자 이내로 입력해주세요");

        RuleFor(x => x.Price)
            .GreaterThan(0).WithMessage("가격은 0보다 큰 값을 입력해주세요");
    }
}

// 유효성 검사 필터 생성
public class ValidationFilter<T> : IEndpointFilter where T : class
{
    private readonly IValidator<T> _validator;

    public ValidationFilter(IValidator<T> validator)
    {
        _validator = validator;
    }

    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        var argument = context.Arguments
            .OfType<T>()
            .FirstOrDefault();

        if (argument is null)
            return Results.BadRequest("요청 본문이 필요합니다");

        var result = await _validator.ValidateAsync(argument);

        if (!result.IsValid)
        {
            var errors = result.Errors
                .GroupBy(e => e.PropertyName)
                .ToDictionary(
                    g => g.Key,
                    g => g.Select(e => e.ErrorMessage).ToArray());
            return Results.ValidationProblem(errors);
        }

        return await next(context);
    }
}

// 필터 적용
group.MapPost("/", CreateProduct)
    .AddEndpointFilter<ValidationFilter<CreateProductRequest>>();

// JWT 인증 설정
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidAudience = builder.Configuration["Jwt:Audience"],
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]!))
        };
    });

builder.Services.AddAuthorizationBuilder()
    .AddPolicy("AdminOnly", policy =>
        policy.RequireRole("Admin"))
    .AddPolicy("CanManageProducts", policy =>
        policy.RequireClaim("permission", "products:write"));

// 엔드포인트에서 권한 부여 적용
var adminGroup = app.MapGroup("/api/admin")
    .RequireAuthorization("AdminOnly");

adminGroup.MapGet("/users", async (IUserRepository repo) =>
    Results.Ok(await repo.GetAllAsync()));

adminGroup.MapDelete("/users/{id}", async (int id, IUserRepository repo) =>
{
    await repo.DeleteAsync(id);
    return Results.NoContent();
});

// Swagger 설정
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Products API",
        Version = "v1",
        Description = "상품 관리 API"
    });

    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT"
    });
});

// 엔드포인트 문서 강화
group.MapGet("/{id:int}", GetProductById)
    .WithName("GetProduct")
    .WithSummary("ID로 상품 조회")
    .WithDescription("지정된 ID의 상품을 조회합니다. 존재하지 않으면 404를 반환합니다.")
    .Produces<Product>(StatusCodes.Status200OK)
    .Produces(StatusCodes.Status404NotFound);

// Rate Limiting 설정
builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("api", config =>
    {
        config.PermitLimit = 100;
        config.Window = TimeSpan.FromMinutes(1);
        config.QueueLimit = 10;
    });
});

app.UseRateLimiter();

app.MapGet("/products", GetAllProducts)
    .RequireRateLimiting("api");

// WebApplicationFactory를 사용한 통합 테스트
public class ProductApiTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HttpClient _client;

    public ProductApiTests(WebApplicationFactory<Program> factory)
    {
        _client = factory.CreateClient();
    }

    [Fact]
    public async Task GetProducts_ReturnsOk()
    {
        var response = await _client.GetAsync("/api/products");
        response.StatusCode.Should().Be(HttpStatusCode.OK);
    }

    [Fact]
    public async Task CreateProduct_WithValidData_ReturnsCreated()
    {
        var request = new { Name = "테스트 상품", Price = 10000 };
        var response = await _client.PostAsJsonAsync("/api/products", request);
        response.StatusCode.Should().Be(HttpStatusCode.Created);
    }
}