Minimal API 是 .NET 6+ 提供的轻量级 Web API 构建方式，适合快速验证、内部工具、微服务边缘端点及教学演示；不适合复杂授权、大量中间件定制或传统 MVC 复用。
Minimal API 是什么，什么时候该用它
Minimal API 是 .NET 6+ 提供的轻量级 Web API 构建方式，不依赖 Controller 类、Startup.cs 或 Program.cs 中繁杂的配置链。它适合快速验证逻辑、写内部工具接口、构建微服务边缘端点，或者教学演示——但不适合需要大量中间件定制、复杂授权策略或传统 MVC 模式复用的项目。
- 如果你只需要暴露几个 HTTP 端点（比如
GET /health、POST /api/users），Minimal API 写起来比 Controller 少一半代码 - 它默认不启用
ModelState验证、不自动绑定IFormFile、不支持[FromRoute]/[FromBody]的显式标注（靠参数类型和命名约定推断） - 所有路由注册、中间件顺序、服务注入都集中在
Program.cs里，没有分离的配置入口
如何在 Program.cs 中注册 Minimal API 路由
.NET 6+ 的 Program.cs 默认是隐式 using + 顶层语句模式，Minimal API 的入口就是 WebApplication.CreateBuilder() 后的 app.MapXxx() 调用。
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer(); // 需要 Swagger 时才加
var app = builder.Build();
<p>app.MapGet("/hello", () => "Hello World");<br />
app.MapPost("/echo", (string name) => $"Hi, {name}!");<br />
app.MapGet("/users/{id}", (int id) => new { Id = id, Name = "Alice" });</p><p>app.Run();</p>- 参数名必须和路由模板中的占位符一致（如
{id}→ 参数名必须是id，大小写敏感） - 复杂对象（如
User）默认从 JSON body 绑定，但要求请求头含Content-Type: application/json，否则返回 400 - 不支持直接绑定查询参数和路径参数混用的复杂模型；想同时读
?page=1和/users/{id}，得拆成两个参数：(int id, int page)
如何处理 JSON 请求体与验证
Minimal API 没有内置的 ModelState，验证得靠手动检查或引入 System.ComponentModel.DataAnnotations + 显式调用 Validator.TryValidateObject。
app.MapPost("/users", (User user) =>
{
var validationContext = new ValidationContext(user);
var results = new List<ValidationResult>();
if (!Validator.TryValidateObject(user, validationContext, results, true))
return Results.BadRequest(results.Select(r => r.ErrorMessage));
<pre class='brush:php;toolbar:false;'>return Results.Ok(user);});
-
User类需标记[Required]、[StringLength]等特性 - 注意：Minimal API 不会自动跳过未标注的属性，所有 public 属性都会参与反序列化（除非用
[JsonIgnore]） - 如果传了非法 JSON（如字段类型错），会直接 400，错误信息极简（只有“Failed to deserialize”），调试时建议开启
app.UseDeveloperExceptionPage()
为什么 MapGet/MapPost 有时不生效或 404
最常见原因是路由注册顺序和中间件位置不对。Minimal API 的 MapXxx 必须在 app.Run() 前，且不能被 app.UseRouting() 或 app.UseEndpoints() 干扰——现代模板已默认隐藏这些，但如果你手动加了旧式中间件，就会冲突。
- 检查是否误写了
app.UseEndpoints(...)：Minimal API 不需要它，加了反而屏蔽MapXxx - 检查路由是否重复：比如先写了
app.MapGet("/api/{*path}", ...)，再写app.MapGet("/api/users", ...)，后者永远不会触发（通配符优先） - 检查 HTTP 方法：用
curl -X POST测试MapGet肯定 405；反过来也一样 - 开发时建议加一句
app.MapFallback(() => Results.NotFound());，方便确认是不是路由根本没匹配上
Minimal API 表面简单，但参数绑定规则、错误传播机制、中间件交互都比 Controller 更“透明”也更易出错——尤其当你从传统 ASP.NET Core 迁移过来时，那些“默认帮你做”的事现在全得自己看清、选对、写准。
