526互联

快速展示原型之Minimal API开发

发布时间 2023-10-19 10:57:51作者: 明志德道

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 中的体现方式：

  1. 路由和端点定义：

    • 使用 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 时，返回相应的信息。

       

  2. 请求和响应处理：

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

    • 使用 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 中如何处理请求和响应。如果你有任何其他问题，请随时提问。

       

  3. 中间件和管道：

    • 使用 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` 方法中打印了一些日志信息，以展示自定义中间件的使用方式。
​

       

  4. 模型绑定和验证：

    • 可以通过方法参数直接进行模型绑定，无需显式地使用 [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]` 等特性。
​

       

  5. 异常处理：

    • 使用 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，并将异常信息写入响应。
​
在应用程序的主函数中，我们注册了自定义的异常处理中间件，并在根路径上抛出一个异常，以模拟应用程序中的异常情况。当访问根路径时，异常处理中间件将捕获并处理异常，并返回相应的错误响应。
​
通过这种方式，你可以自定义异常处理中间件来捕获和处理应用程序中的异常，并生成适当的响应。
​

       

  6. 依赖注入：

    • 使用 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 中方便地使用依赖注入来管理和使用服务。
​

       

  7. 身份验证和授权：

    • 使用 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 中实现身份验证和授权的功能。请注意，这只是一个基本示例，实际应用中可能需要根据具体的需求进行配置和扩展。
​

       

  8. 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。
​
​

       

  9. 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 应用程序，使得代码更加清晰和易于维护。