在ASP.NET Core 6及更高版本中，框架引入了Minimal API这一全新编程模型，让开发者可以用极少的代码暴露HTTP服务。它不再要求创建Controller类、继承基类或写大量样板路由特性，而是直接在应用构建器上以方法链式调用的方式声明端点。这种方式特别适合构建轻量级的内部接口、微服务探针以及快速验证原型的HTTP服务。
Minimal API的核心原理与基础结构
Minimal API的底层依赖于ASP.NET Core的终结点路由系统。当我们在WebApplication实例上调用MapGet、MapPost等方法时，框架会将传入的委托注册为一个终结点，并绑定到对应的HTTP方法与路径模板。请求到达后，路由中间件直接分发到该委托，跳过了传统MVC的控制器激活、模型绑定器复杂管道，因此延迟更低。
一个最基础的Program.cs文件可以仅包含几行代码。下面示例展示如何创建一个返回文本的GET接口，以及接收JSON的POST接口。注意这里使用了顶层语句，不需要显式定义类和Main方法。
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/hello", () => "Hello from Minimal API");
app.MapPost("/echo", (Person p) => Results.Ok(p));
app.Run();
record Person(string Name, int Age);
上述代码中，Results.Ok是Minimal API提供的静态结果助手，用于生成标准HTTP响应。框架会自动使用System.Text.Json对返回对象进行序列化。与MVC不同，这里没有[ApiController]特性，也没有ControllerBase继承，所有逻辑以闭包或局部函数形式存在，显著减少了文件数量。
从设计角度看，Minimal API并不是要取代MVC，而是补足了轻量级场景的空缺。当接口数量少于二三十个、且不需要复杂的过滤器与视图渲染时，它的开发效率优势非常明显。对于需要统一异常处理、请求验证的场景，也可以通过全局中间件或过滤器扩展实现。
参数绑定与依赖注入的实用方式
Minimal API支持多种参数绑定源，包括路由参数、查询字符串、请求头、服务实例等。框架会根据委托参数的类型与名称自动推断来源。例如路径模板中的{id}会绑定到同名的int id参数；类型为已注册服务时，则从依赖注入容器解析。
下面示例演示如何从路径取ID、从查询取名称，并注入一个业务服务。我们定义了一个简单接口及其实现，并在构建器中注册为单例。
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IOrderService, OrderService>();
var app = builder.Build();
app.MapGet("/orders/{id}", (int id, string? q, IOrderService svc) =>
{
var data = svc.GetOrder(id);
return q == null ? Results.Ok(data) : Results.Ok($"{q}: {data}");
});
app.Run();
public interface IOrderService { string GetOrder(int id); }
public class OrderService : IOrderService
{
public string GetOrder(int id) => $"Order-{id}";
}
如果参数来自请求体，Minimal API默认使用JSON绑定。当方法签名包含一个复杂类型且未标明来源时，框架会尝试从body读取。你也可以用[FromQuery]等特性显式指定，不过在Minimal API中更推荐用命名约定保持代码干净。
对于需要事务或数据库上下文的场景，可直接注入DbContext。由于终结点委托是普通方法，你可以方便地使用using语句或异步await调用。这种写法比控制器中分散的构造函数注入更容易做单元测试，因为测试时只需传入模拟服务即可。
返回结果控制与中间件集成策略
Minimal API通过Results类提供了丰富的响应助手，如Results.NotFound、Results.Created、Results.Json等，能精确控制状态码与响应头。对于文件下载，可使用Results.File；对于重定向，使用Results.Redirect。这些助手返回的是IResult接口，框架负责最终写出。
在安全性方面，可以给特定终结点挂载授权策略。下面的代码展示如何用RequireAuthorization扩展方法保护接口，并全局添加跨域中间件。注意中间件顺序很重要，鉴权应在路由之后、终结点之前生效。
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication("Bearer").AddJwtBearer();
builder.Services.AddAuthorization();
var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapGet("/secure", () => "secret")
.RequireAuthorization();
app.MapGet("/open", () => "public");
app.Run();
除了授权，日志与异常处理也能以中间件形式统一处理。比如使用app.UseExceptionHandler捕获终结点内未处理异常，返回标准错误结构。由于Minimal API的委托本质就是请求处理管道的一环，它与现有ASP.NET Core生态完全兼容，你可以复用既有的过滤器逻辑、健康检查与指标收集组件。
当项目规模增长，建议将映射逻辑拆分到独立静态方法中，通过app.MapGroup("/api")进行版本分组，保持Program文件整洁。Minimal API并不限制你组织代码的方式，它只是把最薄的HTTP层交还给开发者，其余能力仍由成熟的ASP.NET Core底座支撑。
MinimalAPIASP.NET Core轻量级HTTP接口修改时间：2026-08-19 05:44:13