快速展示原型之Minimal API开发

Minimal API官网地址: https://learn.microsoft.com/zh-cn/aspnet/core/fundamentals/minimal-apis/security?view=aspnetcore-7.0

Minimal API 背景介绍

Minimal APIs 是指在 ASP.NET Core 中引入的一种轻量级的 API 开发模式。它的产生背景是为了简化 API 的创建和开发流程,减少样板代码,并提供更灵活的方式来定义和配置 API 端点。

在传统的 ASP.NET Core 中,创建 API 需要定义控制器类和路由配置,并编写一系列的动作方法和路由规则。这样的开发模式在一些简单的场景下可能会显得过于繁琐和冗余。

Minimal APIs 的定义和配置更加简洁和直观,可以在一个单独的文件中定义整个 API,而无需创建控制器类和路由配置。它通过使用 Lambda 表达式和链式调用的方式,将路由、HTTP 方法和请求处理逻辑直接绑定在一起,减少了样板代码的数量。

Minimal APIs 的应用场景包括但不限于:

  1. 快速原型开发:在快速原型开发阶段,Minimal APIs 可以帮助开发者快速创建和测试 API 端点,减少开发时间和代码量。

  2. 小型项目和微服务:对于小型项目或者微服务,Minimal APIs 提供了一种简洁的方式来定义和配置 API,减少了项目结构的复杂性。

  3. 单个端点的简单 API:对于只有一个或者少量端点的简单 API,Minimal APIs 可以提供更加直观和简洁的开发方式。

  4. 快速验证和测试:Minimal APIs 可以用于快速验证和测试一些想法或者概念,以及进行一些临时性的 API 开发。

需要注意的是,Minimal APIs 并不适用于所有场景。对于复杂的 API 或者需要更多配置和扩展的情况,传统的控制器和路由配置方式可能更加合适。

功能代码示例

在 Minimal API 中,ASP.NET Core 的一些功能可以通过简化的语法和约定来体现。下面是一些常见的功能在 Minimal API 中的体现方式:

路由和端点定义:

  • 使用 app.MapGet()app.MapPost() 等方法来定义路由和处理不同的 HTTP 请求方法。

  • 可以直接在路由路径中使用参数,如 {name},并将其作为方法参数进行处理。

    var builder = WebApplication.CreateBuilder(args);
    var app = builder.Build();
    ​
    app.MapGet("/", () => "Hello, Minimal API!");
    ​
    app.MapPost("/", () => "Received a POST request!");
    ​
    app.MapPut("/", () => "Received a PUT request!");
    ​
    app.MapDelete("/", () => "Received a DELETE request!");
    ​
    app.MapMethods("/hello", new[] { "GET", "POST", "PUT", "DELETE" }, () =>
    {
        var method = Context.Request.Method;
        return $"Received a {method} request to /hello";
    });
    ​
    app.Run();
    ​
    app.MapGet() 方法用于处理 HTTP GET 请求,当请求的路径为根路径 / 时,返回 "Hello, Minimal API!"。
    app.MapPost() 方法用于处理 HTTP POST 请求,当请求的路径为根路径 / 时,返回 "Received a POST request!"。
    app.MapPut() 方法用于处理 HTTP PUT 请求,当请求的路径为根路径 / 时,返回 "Received a PUT request!"。
    app.MapDelete() 方法用于处理 HTTP DELETE 请求,当请求的路径为根路径 / 时,返回 "Received a DELETE request!"。
    app.MapMethods() 方法用于处理指定的 HTTP 请求方法,当请求的路径为 /hello 且方法为 GET、POST、PUT 或 DELETE 时,返回相应的信息。
    

请求和响应处理:

  • 使用方法参数来获取请求中的数据,如路由参数、查询字符串参数和请求体参数。

  • 使用 Results 类来生成响应,如 Results.Ok()Results.BadRequest() 等。

    var builder = WebApplication.CreateBuilder(args);
    ​
    builder.Services.AddSingleton<ICustomService, CustomService>();
    ​
    var app = builder.Build();
    ​
    app.MapGet("/hello/{name}", (string name) =>
    {
        return $"Hello, {name}!";
    });
    ​
    app.MapPost("/api/submit", async (HttpRequest request) =>
    {
        // 从请求体中获取数据
        var data = await request.ReadFromJsonAsync<CustomData>();
    ​
        // 处理数据并生成响应
        var result = ProcessData(data);
    ​
        return Results.Ok(result);
    });
    ​
    app.Run();
    ​
    public class CustomData
    {
        public string Name { get; set; }
        public int Age { get; set; }
    }
    ​
    public class CustomService : ICustomService
    {
        // 服务实现代码
    }
    ​
    public interface ICustomService
    {
        // 服务接口定义
    }
    ​
    在上面的示例中,我们定义了两个端点:
    ​
    - `GET /hello/{name}`:使用路由参数 `name` 来获取请求中的数据,并返回相应的问候消息。
    - `POST /api/submit`:使用 `HttpRequest` 参数来获取请求体中的数据,并进行处理,然后生成响应。
    ​
    在 `POST /api/submit` 端点中,我们使用 `ReadFromJsonAsync<T>()` 方法从请求体中异步读取 JSON 数据,并将其转换为 `CustomData` 对象。然后,我们可以对数据进行处理,并生成相应的结果。最后,我们使用 `Results.Ok()` 方法将结果作为 JSON 响应返回。
    ​
    希望这个更全面的代码示例能够帮助你理解在 Minimal API 中如何处理请求和响应。如果你有任何其他问题,请随时提问。
    

中间件和管道:

  • 使用 app.UseMiddleware<CustomMiddleware>() 来添加自定义的中间件。

  • 使用 app.MapGet().UseMiddleware<AuthenticationMiddleware>() 在特定的端点上使用中间件。

    ```csharp
    using Microsoft.AspNetCore.Builder;
    using Microsoft.AspNetCore.Http;
    using Microsoft.Extensions.DependencyInjection;
    using System;
    using System.Threading.Tasks;
    ​
    var builder = WebApplication.CreateBuilder(args);
    ​
    // 注册自定义中间件
    builder.Services.AddTransient<CustomMiddleware>();
    ​
    var app = builder.Build();
    ​
    // 使用自定义中间件
    app.UseMiddleware<CustomMiddleware>();
    ​
    // 定义路由和处理请求的方法
    app.MapGet("/", () => "Hello, Minimal API!");
    ​
    app.Run();
    ​
    // 自定义中间件
    public class CustomMiddleware
    {
        private readonly RequestDelegate _next;
    ​
        public CustomMiddleware(RequestDelegate next)
        {
            _next = next;
        }
    ​
        public async Task InvokeAsync(HttpContext context)
        {
            // 在请求处理之前执行的逻辑
            Console.WriteLine("CustomMiddleware: Before request");
    ​
            // 调用下一个中间件或处理程序
            await _next(context);
    ​
            // 在请求处理之后执行的逻辑
            Console.WriteLine("CustomMiddleware: After request");
        }
    }
    ```
    ​
    在上面的示例中,我们首先通过 `builder.Services.AddTransient<CustomMiddleware>()` 将自定义中间件注册到容器中。然后,在 `app.UseMiddleware<CustomMiddleware>()` 中使用自定义中间件。这样,每次请求进入应用程序时,都会先经过自定义中间件的处理。
    ​
    自定义中间件的实现类 `CustomMiddleware` 必须具有 `InvokeAsync` 方法,该方法接收一个 `HttpContext` 对象和一个 `RequestDelegate` 对象作为参数。在 `InvokeAsync` 方法中,我们可以在请求处理之前和之后执行一些逻辑。
    ​
    在上面的示例中,我们在自定义中间件的 `InvokeAsync` 方法中打印了一些日志信息,以展示自定义中间件的使用方式。
    ​
    

模型绑定和验证:

  • 可以通过方法参数直接进行模型绑定,无需显式地使用 [FromBody][FromQuery] 等特性。

  • 使用 ModelState 进行模型验证,并返回相应的结果。

    var builder = WebApplication.CreateBuilder(args);
    ​
    // 定义模型类
    public class Person
    {
        [Required(ErrorMessage = "Name is required")]
        public string Name { get; set; }
    ​
        [Range(18, 100, ErrorMessage = "Age must be between 18 and 100")]
        public int Age { get; set; }
    ​
        public string Email { get; set; }
    }
    ​
    // 注册模型验证器
    builder.Services.Configure<ApiBehaviorOptions>(options =>
    {
        options.InvalidModelStateResponseFactory = context =>
        {
            var errors = new List<string>();
            foreach (var modelState in context.ModelState.Values)
            {
                foreach (var error in modelState.Errors)
                {
                    errors.Add(error.ErrorMessage);
                }
            }
    ​
            return new BadRequestObjectResult(errors);
        };
    });
    ​
    var app = builder.Build();
    ​
    app.MapPost("/person", async (Person person) =>
    {
        if (!ModelState.IsValid)
        {
            return Results.BadRequest(ModelState);
        }
    ​
        // 处理有效的 person 对象
        return Results.Ok(person);
    });
    ​
    app.Run();
    ​
    ```
    ​
    在上面的示例中,我们定义了一个 `Person` 类作为模型,并在属性上使用了一些数据注解来定义验证规则。在 `app.MapPost` 方法中,我们直接将 `Person` 类作为参数,Minimal API 会自动进行模型绑定和验证。如果模型验证失败,我们通过自定义的 `InvalidModelStateResponseFactory` 来返回验证错误信息。
    ​
    当我们发送 POST 请求到 `/person` 路径时,Minimal API 会自动将请求体中的 JSON 数据绑定到 `Person` 对象,并进行模型验证。如果模型验证失败,将返回包含验证错误信息的 BadRequest 响应;如果模型验证成功,将返回包含有效的 `Person` 对象的 Ok 响应。
    ​
    这样,我们就可以通过方法参数来实现模型绑定和验证,而无需显式地使用 `[FromBody]` 或 `[FromQuery]` 等特性。
    ​
    

异常处理:

  • 使用 app.RunExceptionHandler() 来捕获并处理应用程序中的异常。

    var builder = WebApplication.CreateBuilder(args);
    ​
    // 注册自定义的异常处理中间件
    builder.Services.AddSingleton<ExceptionHandlerMiddleware>();
    ​
    var app = builder.Build();
    ​
    // 使用自定义的异常处理中间件
    app.UseMiddleware<ExceptionHandlerMiddleware>();
    ​
    app.MapGet("/", () => throw new Exception("Something went wrong!"));
    ​
    app.Run();
    ​
    // 自定义异常处理中间件
    public class ExceptionHandlerMiddleware
    {
        private readonly RequestDelegate _next;
    ​
        public ExceptionHandlerMiddleware(RequestDelegate next)
        {
            _next = next;
        }
    ​
        public async Task InvokeAsync(HttpContext context)
        {
            try
            {
                // 执行下一个中间件
                await _next(context);
            }
            catch (Exception ex)
            {
                // 处理异常并生成响应
                context.Response.StatusCode = 500;
                await context.Response.WriteAsync($"An error occurred: {ex.Message}");
            }
        }
    }
    ```
    ​
    在上面的代码示例中,我们定义了一个自定义的异常处理中间件 `ExceptionHandlerMiddleware`,它接受一个 `RequestDelegate` 参数作为下一个中间件。在 `InvokeAsync` 方法中,我们使用 `try-catch` 块来捕获应用程序中的异常。如果发生异常,我们设置响应的状态码为 500,并将异常信息写入响应。
    ​
    在应用程序的主函数中,我们注册了自定义的异常处理中间件,并在根路径上抛出一个异常,以模拟应用程序中的异常情况。当访问根路径时,异常处理中间件将捕获并处理异常,并返回相应的错误响应。
    ​
    通过这种方式,你可以自定义异常处理中间件来捕获和处理应用程序中的异常,并生成适当的响应。
    ​
    

依赖注入:

  • 使用 app.Services.AddSingleton<TService, TImplementation>()app.Services.AddScoped<TService, TImplementation>() 将服务注册到容器中。

  • 可以直接在方法参数中使用依赖注入的服务。

    当使用 Minimal API 进行开发时,可以使用依赖注入来注册和使用服务。下面是一个更全面的代码示例,演示了如何在 Minimal API 中使用依赖注入:
    ​
    ```csharp
    using Microsoft.AspNetCore.Builder;
    using Microsoft.AspNetCore.Http;
    using Microsoft.Extensions.DependencyInjection;
    ​
    var builder = WebApplication.CreateBuilder();
    ​
    // 注册服务
    builder.Services.AddSingleton<IMyService, MyService>();
    ​
    var app = builder.Build();
    ​
    // 使用服务
    app.MapGet("/", (IMyService myService) =>
    {
        var result = myService.DoSomething();
        return result;
    });
    ​
    app.Run();
    ​
    // 服务接口
    public interface IMyService
    {
        string DoSomething();
    }
    ​
    // 服务实现
    public class MyService : IMyService
    {
        public string DoSomething()
        {
            return "Hello from MyService!";
        }
    }
    ```
    ​
    在上面的示例中,我们首先使用 `builder.Services.AddSingleton<IMyService, MyService>()` 将 `MyService` 注册为 `IMyService` 接口的实现,这样就可以在应用程序中使用 `IMyService` 进行依赖注入。
    ​
    然后,在 `app.MapGet()` 方法中,我们将 `IMyService` 作为参数传入,Minimal API 将自动从容器中解析并提供一个 `IMyService` 实例。在处理请求时,我们可以直接使用 `myService` 来调用 `IMyService` 中的方法。
    ​
    这样,我们就可以在 Minimal API 中方便地使用依赖注入来管理和使用服务。
    ​
    

身份验证和授权:

  • 使用 app.UseAuthentication()app.UseAuthorization() 启用身份验证和授权中间件。

  • 使用 RequireAuthorization() 方法来标记需要进行身份验证和授权的端点。

    ​
    1. 首先,确保已经在项目中添加了所需的身份验证和授权相关的 NuGet 包,如 `Microsoft.AspNetCore.Authentication` 和 `Microsoft.AspNetCore.Authorization`。
    ​
    2. 在 `Program.cs` 文件中,使用 `builder.Services.AddAuthentication()` 和 `builder.Services.AddAuthorization()` 方法来注册身份验证和授权服务:
    ​
    ```csharp
    var builder = WebApplication.CreateBuilder(args);
    ​
    // 注册身份验证服务
    builder.Services.AddAuthentication(options =>
    {
        options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
    })
    .AddJwtBearer(options =>
    {
        // 配置 JWT Bearer 认证选项
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = Configuration["Jwt:Issuer"],
            ValidAudience = Configuration["Jwt:Audience"],
            IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(Configuration["Jwt:Key"]))
        };
    });
    ​
    // 注册授权服务
    builder.Services.AddAuthorization();
    ​
    var app = builder.Build();
    ```
    ​
    3. 在 `Configure` 方法中,使用 `app.UseAuthentication()` 和 `app.UseAuthorization()` 方法来启用身份验证和授权中间件:
    ​
    ```csharp
    app.UseAuthentication();
    app.UseAuthorization();
    ```
    ​
    4. 在需要进行身份验证和授权的端点上,使用 `RequireAuthorization()` 方法来标记需要进行身份验证和授权的端点:
    ​
    ```csharp
    app.MapGet("/hello", () => "Hello, Minimal APIs!")
        .RequireAuthorization();
    ```
    ​
    5. 在需要进行授权的端点上,可以使用 `[Authorize]` 特性来标记需要进行授权的端点:
    ​
    ```csharp
    app.MapGet("/secret", () => "This is a secret page.")
        .RequireAuthorization()
        .WithMetadata(new AuthorizeAttribute());
    ```
    ​
    6. 在需要获取当前用户信息的地方,可以通过方法参数的方式获取 `HttpContext`,并使用 `User` 属性来获取当前用户的身份信息:
    ​
    ```csharp
    app.MapGet("/profile", (HttpContext context) =>
    {
        var user = context.User;
        // 获取用户信息并进行处理
        // ...
        return "User Profile";
    })
    .RequireAuthorization();
    ```
    ​
    通过以上代码示例,你可以在 Minimal API 中实现身份验证和授权的功能。请注意,这只是一个基本示例,实际应用中可能需要根据具体的需求进行配置和扩展。
    ​
    

Swagger:

  • 使用 app.UseSwagger()app.UseSwaggerUI() 启用 Swagger 支持和 Swagger UI。

    ​
    var builder = WebApplication.CreateBuilder(args);
    ​
    // 添加 Swagger
    builder.Services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });
    ​
    var app = builder.Build();
    ​
    // 启用 Swagger UI
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1");
    });
    ​
    app.MapGet("/", () => "Hello, Minimal APIs!");
    ​
    app.Run();
    ```
    ​
    在上述示例中,我们首先在 `CreateHostBuilder` 方法中使用 `AddSwaggerGen` 方法配置 Swagger,指定了 API 的标题和版本信息。
    ​
    然后,在应用程序构建完成后,我们使用 `UseSwagger` 方法启用 Swagger 支持,并使用 `UseSwaggerUI` 方法配置 Swagger UI 的终结点。
    ​
    最后,我们定义了一个简单的根路径处理程序,以便在浏览器中查看 Swagger UI。
    ​
    运行应用程序后,你可以通过访问 `http://localhost:5000/swagger` 来查看 Swagger UI,并浏览和测试你的 API。
    ​
    ​
    

Filter:

  • 使用 app.AddFilter<CustomFilter>() 将过滤器添加到应用程序。

    当使用 Minimal API 开发时,可以通过自定义 Filter 来实现全局的过滤器功能。下面是一个更全面的代码示例:
    ​
    1. 创建自定义的过滤器类 `CustomFilter`:
    ​
    ```csharp
    public class CustomFilter : IAsyncActionFilter
    {
        public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
        {
            // 在执行操作之前的逻辑
            Console.WriteLine("Before action execution");
    ​
            // 执行下一个过滤器或操作
            var resultContext = await next();
    ​
            // 在执行操作之后的逻辑
            Console.WriteLine("After action execution");
        }
    }
    ```
    ​
    2. 在应用程序中注册过滤器:
    ​
    ```csharp
    var builder = WebApplication.CreateBuilder(args);
    ​
    // 注册过滤器
    builder.Services.AddFilter<CustomFilter>();
    ​
    var app = builder.Build();
    ​
    app.MapGet("/", () => "Hello, Minimal APIs!")
        .RequireAuthorization()
        .WithFilter<CustomFilter>(); // 添加过滤器到端点
    ​
    app.Run();
    ```
    ​
    在上面的示例中,我们创建了一个名为 `CustomFilter` 的自定义过滤器类,并实现了 `IAsyncActionFilter` 接口。在 `OnActionExecutionAsync` 方法中,我们可以编写在执行操作之前和之后需要执行的逻辑。
    ​
    在应用程序中,我们使用 `builder.Services.AddFilter<CustomFilter>()` 将自定义过滤器添加到服务容器中。然后,我们在 `app.MapGet()` 方法链中使用 `.WithFilter<CustomFilter>()` 将过滤器添加到特定的端点。
    ​
    当请求到达该端点时,过滤器的逻辑将在执行操作之前和之后被调用。
    ​
    

通过这些简化的语法和约定,Minimal API 提供了一种更简洁、更直观的方式来开发和配置 ASP.NET Core 应用程序,使得代码更加清晰和易于维护。