在 ASP.NET Core 6 之后，微软引入了一种新的接口编写方式，开发者可以不定义 Controller 类，直接在主程序文件里用极简的语法完成路由注册与请求处理。这种方式被称为 Minimal APIs，它把原先分散在 Controller、Startup、路由表里的逻辑收敛到一条清晰的委托链中。从底层看，Minimal APIs 本质上是把终结点（Endpoint）直接挂到应用的中间件管道上，由框架在启动时做轻量绑定，而不是像 MVC 那样经过完整的控制器激活、模型绑定器和过滤器管道。
Minimal APIs 的核心工作机制
Minimal APIs 的核心是 WebApplication 对象暴露的 MapGet、MapPost 等扩展方法。这些方法接收路由模板和一个请求委托，框架会在配置阶段将该委托包装成终结点元数据。与 MVC 不同，它不需要通过反射扫描程序集里的 Controller 类型，因此应用启动时的类型发现成本显著降低。参数绑定也得到简化，基础类型直接从路由或查询字符串解析，复杂对象则使用内置的 JSON 序列化器。
下面的代码展示了一个最基础的 Minimal API，它仅用四行就完成了服务构建与响应输出：
var app = WebApplication.Create(args);
app.MapGet("/hello/{name}", (string name) =>
Results.Ok(new { message = $"你好, {name}" }));
app.Run();
从上述示例可以看出，路由参数 name 被自动绑定到委托的入参。框架在内部使用 RequestDelegate 工厂生成执行逻辑，省去了 Controller 激活器（Controller Activator）的调用。这种机制让单接口的冷启动时间更短，在容器化环境中能更快通过健康检查。不过需要注意，Minimal APIs 默认不开启 MVC 的模型验证管道，开发者要自行处理非法输入。
与传统 Controller 模式的差异对比
传统 ASP.NET Core MVC 使用 [ApiController] 和 ControllerBase 派生类来组织接口，每个 Action 方法通过路由特性或约定映射到 URL。这种方式拥有成熟的过滤器（Filter）、依赖注入构造函数注入、以及统一的模型验证返回格式。而 Minimal APIs 更倾向于函数式风格，依赖通过委托入参或全局服务定位器获取，结构上更扁平。
在代码组织上，Controller 适合按业务域划分多个类文件，便于中大型团队维护；Minimal APIs 如果全部写在 Program.cs 里，会导致单一文件膨胀。实践中可以用局部类或独立静态方法拆分，但本质上仍缺少框架级的约定约束。下面的表格列出了两者在几个关键维度上的区别：
| 维度 | Minimal APIs | 传统 Controller |
|---|---|---|
| 启动性能 | 较高，无反射扫描 | 较低，需扫描控制器 |
| 代码体量 | 极少，适合小服务 | 结构重，适合复杂系统 |
| 依赖注入 | 方法入参或服务定位 | 构造函数注入 |
| 过滤器支持 | 需手动加中间件 | 原生 Filter 管道 |
从维护角度看，当项目接口超过三十个且业务逻辑交织时，纯 Minimal APIs 会让 Program.cs 变得难以阅读。此时可以保留 Minimal APIs 做边缘服务，核心域仍用 Controller。两者在同一应用内完全可以共存，框架不强制二选一。
何时该选用 Minimal APIs 以及避坑建议
Minimal APIs 最适宜的场景是内部工具接口、Serverless 函数移植、以及原型验证。例如一个只做 Webhook 转发的代理服务，用 Minimal APIs 能在几分钟内上线，且镜像体积更小。它降低了新手理解 ASP.NET Core 的门槛，不必先弄懂 MVC 的生命周期也能写出可用接口。
但在使用时有几个常见误区。第一，不要为了“极简”把数据库上下文直接塞进委托闭包，这会导致连接池难以管理；应当通过入参声明 DbContext 由框架注入。第二，复杂鉴权不要手写在委托里，应封装成中间件或调用 RequireAuthorization 扩展。第三，返回类型尽量用 Results 静态类，而非直接写 string，这样框架才能正确协商内容类型。下面示例演示了带注入和授权的写法：
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IClock, SystemClock>();
var app = builder.Build();
app.MapGet("/time", (IClock clock) =>
Results.Json(new { now = clock.Now }))
.RequireAuthorization("basic");
app.Run();
public interface IClock { DateTime Now { get; } }
public class SystemClock : IClock { public DateTime Now => DateTime.UtcNow; }
整体而言，Minimal APIs 是 ASP.NET Core 对轻量级开发体验的回应，它不神秘，只是把原有管道做了减法。团队在选型时只需评估接口规模与长期维护成本，不必盲目追新，也无需固守 Controller。理解其绑定与管道本质，才能在合适的土壤里发挥它的价值。
Minimal_APIsASP.NET_CoreController修改时间：2026-08-16 01:50:26