ASP.NET Core 最小API与控制器API的架构差异
核心架构对比
在ASP.NET Core中，最小API（Minimal API）和基于控制器的API代表了两种不同的应用设计范式。最小API采用函数式编程风格，将路由与处理逻辑直接绑定；而控制器模式则遵循面向对象结构，通过类组织业务逻辑。
项目初始化差异
创建最小API时使用"空Web"模板，生成的Program.cs仅包含基础构建器和运行配置：
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.Run();控制器项目则基于"ASP.NET Core Web API"模板，需显式注册控制器服务：
builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();路由定义机制
最小API支持内联路由声明，使用Map{Verb}方法直接绑定请求类型与处理函数：
app.MapGet("/users/{id}", (int id) => $"User {id}");
app.MapPost("/login", (LoginRequest req) => ...);控制器依赖属性路由，通过特性定义路径和行为：
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
[HttpGet("{id}")]
public IActionResult Get(int id) => Ok(new { Id = id });
}参数绑定方式
最小API支持自动绑定，参数名与路由或查询字符串匹配即可：
app.MapGet("/search", (string q, int page = 1) =>
Results.Ok($"Query: {q}, Page: {page}"));控制器必须显式标注绑定源：
[HttpGet("search")]
public IActionResult Search([FromQuery] string q, [FromQuery] int page)依赖注入实现
最小API可在处理程序中直接注入服务：
app.MapGet("/data", (IDataService service, ILogger<Program> log) =>
Results.Ok(service.GetData()));控制器通过构造函数注入：
public class DataController : ControllerBase
{
private readonly IDataService _service;
public DataController(IDataService service) => _service = service;
}模型验证机制
最小API需手动调用验证器：
app.MapPost("/user", (UserDto dto, IValidator<UserDto> validator) =>
{
var result = validator.Validate(dto);
return result.IsValid ? Results.Created(...) : Results.ValidationProblem(result);
});控制器通过[ApiController]特性自动触发验证，失败时返回400状态码：
[HttpPost]
public IActionResult CreateUser(UserDto dto) => Created(...); // 验证失败不执行此逻辑异常处理策略
最小API可自定义异常处理中间件：
app.UseExceptionHandler(context =>
context.Response.WriteAsJsonAsync(new { error = "Internal server error" }));控制器可通过全局异常过滤器集中处理：
services.Configure<ApiBehaviorOptions>(options =>
options.InvalidModelStateResponseFactory = context =>
new ValidationProblemDetails(context.ModelState));OpenAPI文档支持
最小API通过扩展方法配置Swagger：
app.MapGet("/users/{id}", (int id) => ...)
.WithName("GetUser")
.WithTags("Users")
.Produces<UserDto>(200)
.Produces(404);控制器使用XML注释和特性声明：
[HttpGet("{id}")]
[ProducesResponseType(typeof(UserDto), 200)]
[ProducesResponseType(404)]
public async Task GetUser(int id) 适用场景建议
- 最小API：健康检查、版本信息、Webhook回调、静态数据接口等轻量级端点
- 控制器：复杂业务逻辑、权限敏感操作、需要过滤器链的模块化接口
- 混合架构：推荐结合使用，以兼顾性能与可维护性
// 混合部署示例
app.MapGet("/health", () => Results.Ok(new { status = "healthy" }));
app.MapGroup("/api/public").MapGet("/ping", () => Results.Ok("pong"));
app.MapControllers(); // 复杂业务走控制器
app.MapPost("/webhooks/payment", ([FromBody] PaymentEvent evt) => ...);