加完 Controller 的那次构建,我先担心的不是功能对不对,而是两套路由会不会打架。一个项目里同时躺着 app.MapGet("/api/items", ...) 和一个标了 [Route("api/v2/items")] 的控制器,听起来就像两个人在同一张地图上画线。实际跑下来,只要路径分开,两边互不干扰:minimal API 的 /api/items 返回 id 为 1 的条目,Controller 的 /api/v2/items 返回另一份列表,两个 id 各自递增,谁也没挡住谁。
真正让人困惑的不是「能不能共存」,而是「请求到底走了哪条路」。同一个 URL,方法不对会返回 405 还是 404?路由模板里的 {id:long} 到底约束了什么?为什么有的参数从 URL 来,有的从请求体来,有的直接注入?为什么 UseAuthorization 写在端点注册后面就失效?这些问题都指向同一个东西:请求管道。
这篇把同一个「条目」接口用两种写法各实现一遍,跑通之后对照着看差异。第 1 篇的进程和 Kestrel 已经就位,这篇只管进程内部这一段路。文中 minimal API 和 Controller 返回的数据都是本机实测,Controller 的过滤器、[FromServices] 这类没跑过的写法会单独标出来。
两套写法并存:先跑通,再对照
项目在第 1 篇的基础上加一个包,EF Core 的 SQLite 提供程序,用来让两个写法共享同一份数据。第 3 篇会专门讲它,这里先照抄配置,知道「有个数据库」就够了:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="8.0.11" />
</ItemGroup>
</Project>
构建命令和实测输出如下,增量构建 18.52 秒,0 警告 0 错误:
dotnet build
Time Elapsed 00:00:18.52
项目按职责分成四个位置,两套写法各有自己的文件:
Program.cs 里同时注册 minimal API 和 Controller。注意 AddControllers() 和 MapControllers() 是成对的,只加其中一个,控制器就像没被登记过一样,请求会直接落到 404:
using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<AppDb>(o => o.UseSqlite("Data Source=app.db"));
builder.Services.AddControllers();
var app = builder.Build();
using (var scope = app.Services.CreateScope())
{
var db = scope.ServiceProvider.GetRequiredService<AppDb>();
db.Database.EnsureCreated();
}
app.MapPost("/api/items", (ItemInput input, AppDb db) =>
{
var item = new Item { Name = input.Name };
db.Items.Add(item);
db.SaveChanges();
return Results.Json(new { item.Id, item.Name }, statusCode: 201);
});
app.MapGet("/api/items/{id:long}", (long id, AppDb db) =>
{
var item = db.Items.Find(id);
return item is null
? Results.Json(new { error = "not found" }, statusCode: 404)
: Results.Json(new { item.Id, item.Name });
});
app.MapControllers();
app.Run();
public class Item { public long Id { get; set; } public string Name { get; set; } = ""; }
public record ItemInput(string Name);
public class AppDb : DbContext
{
public AppDb(DbContextOptions<AppDb> options) : base(options) { }
public DbSet<Item> Items => Set<Item>();
}
控制器单独放一个文件。它的路由前缀写在类上,具体路径写在方法上,两者拼起来才是完整 URL。[ApiController] 是一个组合开关,打开后参数校验失败会自动返回 400,绑定来源也有默认约定:
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
[ApiController]
[Route("api/v2/items")]
public class ItemsController : ControllerBase
{
private readonly AppDb _db;
public ItemsController(AppDb db) { _db = db; }
[HttpGet]
public IActionResult List() =>
Ok(_db.Items.Select(i => new { i.Id, i.Name }).ToList());
[HttpPost]
public IActionResult Create([FromBody] ItemInput input)
{
var item = new Item { Name = input.Name };
_db.Items.Add(item);
_db.SaveChanges();
return CreatedAtAction(nameof(Get), new { id = item.Id }, new { item.Id, item.Name });
}
[HttpGet("{id:long}")]
public IActionResult Get(long id)
{
var item = _db.Items.Find(id);
return item is null
? NotFound(new { error = "not found" })
: Ok(new { item.Id, item.Name });
}
}
构建通过后启动,按顺序请求:先往 minimal API 写一条,再读 Controller 的列表,再往 Controller 写一条,最后查一个不存在的 id:
curl.exe -s -X POST 127.0.0.1:18082/api/items -H "Content-Type: application/json" -d "{\"name\":\"widget\"}"
{"id":1,"name":"widget"}
curl.exe -s 127.0.0.1:18082/api/v2/items
[{"id":1,"name":"widget"}]
curl.exe -s -i -X POST 127.0.0.1:18082/api/v2/items -H "Content-Type: application/json" -d "{\"name\":\"widget\"}"
HTTP/1.1 201 Created
Location: /api/v2/items/2
{"id":2,"name":"widget"}
curl.exe -s -i 127.0.0.1:18082/api/v2/items/99
HTTP/1.1 404 Not Found
{"error":"not found"}
两件事值得注意。第一,两个写法共用同一个 AppDb,也共用同一张表,所以第一条数据在 Controller 的列表里立刻可见,这不是同步,是同一个数据库。第二,CreatedAtAction 自动生成了 Location 头,值是 /api/v2/items/2,告诉客户端新资源在哪;手写 minimal API 的 201 没有这个头,需要自己加。这就是两类写法在「细节完备度」上的典型差别。
这次实验还有一个副产品:两套写法共用同一个 AppDb 的注册,但每个请求各自拿到一个新实例。Controller 的构造函数注入和 minimal API 的参数注入看起来不一样,落到容器里其实是同一件事,都是「按请求创建一个 scoped 对象」。所以第 2 条数据能被第 1 条请求看见,靠的是数据库,不是内存共享。这个区别在第 3 篇会变成主要话题。
路由模板与参数绑定:值从哪来
路由的职责只有一件事:把请求的「方法加路径」匹配到某个处理函数。模板里的花括号是占位符,冒号后面是约束。约束不满足时,请求根本不会进入函数,表现就是 404,而不是进了函数再报错。这一点很容易误判成「我的代码没被执行」,其实是路由层就拦下了。
/api/items/1 里的 1。模板写成 {id},加了 :long 就只接受整数。?page=2。简单类型参数如果没有出现在路由模板里,默认从查询串绑定。[FromBody]。第 1 篇的 /api/items/{id:long} 就是路径段加约束的例子。约束有三个实际作用:一是把「id 必须是数字」这件事提前到路由层,非法值不会被业务代码当成 0 处理;二是让同一个前缀下的多条路由能区分开;三是错误更早暴露,客户端拿到 404 而不是 500。常用的约束还有 :int、:guid、:min(1) 这类长度或范围限制。
匹配还有一条容易忽略的规则:字面量路径优先于参数路径。比如同时注册 /api/items/latest 和 /api/items/{id},请求 /api/items/latest 会命中前者,而不是把 latest 当作 id。框架按「更具体者优先」排序,不需要你手动控制注册顺序。但两条模板如果具体程度相同、又都能匹配同一个 URL,就会报匹配到多个端点,这类冲突只在请求到达时才暴露。
绑定还有一个反直觉的点:同一个 ItemInput 类型,在 minimal API 里写成 (ItemInput input) 就会自动去读请求体,在 Controller 里写成 (ItemInput input) 却会尝试从查询串绑定,必须补 [FromBody]。原因是两者的绑定规则不同:minimal API 把复杂类型默认当体,Controller 的 [ApiController] 虽然也会对复杂类型默认用体,但只要参数来源有歧义就会退化成查询串。实际项目里最稳的做法是显式写出来,别依赖默认值。
HttpContext 也能直接注入。需要读请求头、拿客户端 IP、写响应状态码时,把它作为参数写进处理函数即可,框架会传当前请求的上下文进来。它相当于整个请求的「总开关」,第 4 篇的令牌解析就会用到它。
管道顺序:注册的先后就是执行的先后
中间件(middleware,包在请求外面的一层处理逻辑)是按注册顺序执行的。请求从最外层往里走,响应再从里往外返回。顺序错了不会报错,只会表现成「功能没生效」,这是最难查的一类问题。
中间件还有一个能力叫短路:某一层直接写响应并返回,后面的层就不执行了。认证失败返回 401、限流拒绝返回 429、静态文件命中直接返回文件,都是短路。短路能省掉后面的开销,但也意味着「后面的日志中间件看不到这个请求」。所以日志中间件要放在靠前的位置,否则被短路掉的请求没有访问记录,排查时会误以为请求根本没到。
三个顺序规则要记牢。第一,UseRouting 必须在 UseAuthorization 之前,因为授权要读「当前匹配到的端点上有哪些要求」,路由还没算出来,它就没东西可读。第二,UseAuthentication 必须在 UseAuthorization 之前,否则授权时还不知道用户是谁,所有需要登录的端点都会判失败。第三,端点注册(MapGet、MapControllers)要放在这些中间件之后,它们只是往路由表里登记,本身不是立即执行的逻辑。
写成代码是这样,WebApplication 会自动补上一些默认中间件,但显式写的这几个位置是有意义的:
var app = builder.Build();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.MapGet("/api/public", () => Results.Json(new { ok = true }));
app.MapGet("/api/private", () => Results.Json(new { ok = true })).RequireAuthorization();
app.MapControllers();
app.Run();
如果你把 UseAuthorization 挪到 MapGet 后面,/api/private 就会变成谁都能访问。RequireAuthorization 只是给端点贴了个标签,真正执行判断的是中间件,标签贴得再对,没人读也白搭。这类故障在日志里没有任何痕迹,只能靠读代码顺序发现。
同一个接口,两种写法
把「创建条目」这一个动作分别用两种写法实现,差异就变得很具体。功能完全一样,返回的状态码和 JSON 也一样,区别在代码放哪、元数据怎么写、扩展点叫什么名字。
Minimal API
处理函数是一个 lambda,直接写在 MapPost 里。参数就是依赖,要数据库就声明 AppDb db,要请求体就声明输入类型。返回 Results.Json 加状态码。扩展点叫 endpoint filter,挂在端点或分组上,能读参数、能短路。
Controller
动作是一个方法,路由前缀在类上、路径在方法上。依赖通过构造函数注入,请求体用 [FromBody] 标出来,返回 Ok、NotFound 这类结果对象。扩展点叫 action filter,能拿到 action 的元数据,也能在动作前后插入逻辑。
两个扩展点解决的是同一类问题:在业务代码之前或之后插一段通用逻辑。对应关系可以用一句话概括:endpoint filter 对应 action filter,端点分组 MapGroup 对应控制器上的路由前缀,RequireAuthorization 对应动作上的授权特性。会其中一个,另一个只是换个写法。
但两者并不完全对等。action filter 能拿到控制器类型、动作名、参数描述这些更丰富的元数据,MVC 生态里的很多库依赖它;endpoint filter 拿到的是端点本身,够用但信息少一些。所以如果项目里已经有大量基于 action filter 的现成逻辑,比如统一的审计、统一的返回包装,硬迁到 minimal API 需要重写这些扩展,这部分成本要提前算。
还有一处细节差别是返回头。CreatedAtAction 会自动算出新资源的地址并放进 Location,minimal API 要自己 Results.Created(url, body) 才有。REST 规范里 201 建议带 Location,团队如果按规范验收,这个差别会被测出来。
[FromServices] 注入、模型验证失败自动 400 这些行为,本机没有逐一实测,这里只按框架文档描述。minimal API 的 endpoint filter 同样没有实测。上面跑过的只有路由、绑定、201 与 404 这些结果。路由和鉴权出问题时,先看这张表
管道和路由的故障有一个共同点:现象都很像,原因却分好几层。下面这张表按「先看到什么」组织,方便你从现象倒推:
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| Controller 的接口全是 404,minimal API 正常 | 只调了 AddControllers 没调 MapControllers,或反过来 | Program.cs 里搜这两个方法是否成对出现 |
| 路径正确却返回 405 | 路径匹配上了,但 HTTP 方法不匹配 | 看处理函数用的是 MapGet 还是 MapPost |
{id:long} 传了字母,返回 404 而非 400 | 约束在路由层就拒绝了,没进入函数 | 确认路径段的值类型,再查模板里的约束 |
| 请求体里的字段全是空值 | 参数被当成查询串绑定,体没被读 | 检查有没有写 [FromBody],或内容类型是否正确 |
| 加了 RequireAuthorization 仍然匿名可访问 | UseAuthorization 注册位置在端点注册之后 | 看中间件三行的相对顺序 |
| 登录成功但接口仍返回 401 | UseAuthentication 没在 UseAuthorization 之前 | 同上,确认认证中间件是否真的注册了 |
| 两套写法路径写重了,请求报匹配到多个端点 | 同一方法和路径被注册了两次 | 全局搜路由字符串,确认前缀没有重叠 |
| 服务容器里拿不到 DbContext | 没注册,或注册的生命周期不对 | 看 AddDbContext 是否在 Build 之前调用 |
表里最反直觉的是 405 和 404 的区别。路径存在但方法不对,框架返回 405 并带上 Allow 头,告诉你这个路径支持哪些方法;路径根本不存在才是 404。很多人把 405 当成「路由没注册」,于是反复检查 MapControllers,其实方向完全错了。先看状态码,再看 Allow 头,比翻代码快得多。
排查顺序建议固定成三步:先看状态码属于 2xx、4xx 还是 5xx,是 4xx 再分 404、405、401、403;再看响应头里有没有 Allow、WWW-Authenticate 这类提示;最后才去读路由表和中间件顺序。反过来先读代码,等于在几百行里找一个可能根本不存在的问题。把这三步变成习惯,路由类故障的定位时间能从半小时降到几分钟。
另一个高频误判是「约束当成校验」。路由约束只保证「能匹配到」,不保证「值一定合法」。比如 {id:long} 能拦住字母,但拦不住负数;{id:min(1)} 能拦住 0 和负数,却拦不住「这个 id 不存在」。业务层面的校验永远要在处理函数里再做一遍,两层各管一段,不能互相替代。
边界与代价:什么时候该停手
两套写法并存的代价,首先是阅读成本。项目里同时存在 /api/items 和 /api/v2/items,看起来像版本演进,实际可能只是两个人在两个时间点选了不同写法。半年后没人记得为什么有两套,新人改动时容易只改一边,另一边悄悄过期。真要并存,路径前缀必须体现「这是另一套」,并在文档里写清楚边界,不能靠猜。
第二个代价是中间件位置变成隐式约定。minimal API 的 WebApplication 会自动把路由和端点放在合理位置,所以小项目里顺序错了也可能碰巧能跑;一旦项目变大,有人手动插了一个 UseMiddleware,隐式约定就被打破。规模上的经验值:中间件超过五层、或者出现第二个开发者手写的中间件时,就该在 Program.cs 里把顺序写成注释,或者干脆抽成一个 UseAppPipeline 扩展方法。
第三个代价是过滤器能力的错配。Controller 的 action filter 生态成熟,很多审计、缓存、返回包装的库直接可用;minimal API 的 endpoint filter 更年轻,能做的事少一些,遇到复杂需求要自己写。什么时候必须用 Controller?当团队依赖这些现成扩展、或者端点超过五十个需要按控制器分组时。反过来,端点少于三十个、只有一两个人维护、且没有复杂过滤器需求时,minimal API 的简洁就是净收益,没必要为了「以后可能变大」提前上 Controller。
SaveChanges 和 Controller 里一次 SaveChanges 是两次独立提交,中间进程退出就会留下半份数据。这不是路由问题,但两套并存会让人误以为它们是一个整体。第 3 篇会讲事务边界。最后是测试成本。两套写法的集成测试入口不同,minimal API 可以用 WebApplicationFactory 统一测,Controller 也能,但测试里对路由的断言写法不一样。项目里两种都有时,测试代码也要维护两套风格,这部分开销在估算工期时经常被忽略。
还有一个隐性代价:两套写法的错误返回格式容易分叉。Controller 里用 NotFound(new { error = "not found" }) 返回自定义 JSON,minimal API 里也是手写的,只要有人改了一边,客户端就会遇到两种错误结构。规范的做法是把错误返回抽成一个公共方法,两边都调用它,别各写一份。
今天就能自验的五个练习
每条都要求你亲手改一处、看一次结果,不要只看结论:
- 把
/api/v2/items改成/api/items,让两套路径完全重合,请求一次,观察返回的错误文本。然后改回去,确认两套又能共存。 - 用
curl.exe -i -X PUT 127.0.0.1:18082/api/v2/items/1打一个没实现的方法,看 405 响应里的Allow头列出了哪些方法。 - 把
{id:long}改成{id},再请求/api/items/abc,对比两次的状态码。这一步能让你分清「路由拦住」和「代码没找到」。 - 故意删掉
[FromBody],POST 一条数据,观察服务端拿到的字段值。再把它加回去,对比结果。 - 把
app.UseAuthorization()移到app.MapGet之后,给一个端点加RequireAuthorization,不带任何凭据请求它。第 4 篇会解释为什么它变成了匿名可访问。
小结
下一篇讲数据访问。上面两个写法都在用 AppDb,但 DbContext 是 scoped 的,一个请求一个实例,把它注入到单例里、或者跨请求缓存起来,都会出问题;EnsureCreated 也只适合演示,正式项目要换成迁移。这些坑在第 2 篇里只是「能跑」,第 3 篇才会拆开。
这篇的三句话总结:第一,路由模板里的约束在进入处理函数之前就生效,404 不一定是代码没写,可能是路由层拦下了;第二,中间件顺序就是注册顺序,UseRouting、UseAuthentication、UseAuthorization 三步顺序错了不会报错,只会让鉴权静默失效;第三,minimal API 和 Controller 能共存,但路径必须分开,团队规模超过四个人、端点超过五十个、或者依赖成熟过滤器生态时,Controller 更划算。