加完 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 端点,以及 AppDb 与实体定义
ItemsController.csController 写法的全部动作
app.dbSQLite 数据文件,首次启动时生成,两套写法共用

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,而不是进了函数再报错。这一点很容易误判成「我的代码没被执行」,其实是路由层就拦下了。

路径段写在 URL 的路径里,如 /api/items/1 里的 1。模板写成 {id},加了 :long 就只接受整数。
查询串URL 里问号之后的部分,如 ?page=2。简单类型参数如果没有出现在路由模板里,默认从查询串绑定。
请求体POST 和 PUT 带的那段 JSON。minimal API 对复杂类型默认从体绑定,Controller 需要显式 [FromBody]。
服务容器处理函数参数里声明一个已注册的服务类型,框架直接从依赖注入容器取,不用你 new。

第 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算出这个 URL 匹配到哪个端点
UseAuthentication解析令牌,确定「你是谁」
UseAuthorization读端点上的要求,判断「能不能进」
端点真正执行处理函数,写回响应

三个顺序规则要记牢。第一,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,团队如果按规范验收,这个差别会被测出来。

Controller 的 action filter、[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 注册位置在端点注册之后看中间件三行的相对顺序
登录成功但接口仍返回 401UseAuthentication 没在 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。

两套写法共用一份数据库时,注意它们各自的事务边界。minimal API 里一次 SaveChanges 和 Controller 里一次 SaveChanges 是两次独立提交,中间进程退出就会留下半份数据。这不是路由问题,但两套并存会让人误以为它们是一个整体。第 3 篇会讲事务边界。

最后是测试成本。两套写法的集成测试入口不同,minimal API 可以用 WebApplicationFactory 统一测,Controller 也能,但测试里对路由的断言写法不一样。项目里两种都有时,测试代码也要维护两套风格,这部分开销在估算工期时经常被忽略。

还有一个隐性代价:两套写法的错误返回格式容易分叉。Controller 里用 NotFound(new { error = "not found" }) 返回自定义 JSON,minimal API 里也是手写的,只要有人改了一边,客户端就会遇到两种错误结构。规范的做法是把错误返回抽成一个公共方法,两边都调用它,别各写一份。

今天就能自验的五个练习

每条都要求你亲手改一处、看一次结果,不要只看结论:

  1. 把 /api/v2/items 改成 /api/items,让两套路径完全重合,请求一次,观察返回的错误文本。然后改回去,确认两套又能共存。
  2. 用 curl.exe -i -X PUT 127.0.0.1:18082/api/v2/items/1 打一个没实现的方法,看 405 响应里的 Allow 头列出了哪些方法。
  3. 把 {id:long} 改成 {id},再请求 /api/items/abc,对比两次的状态码。这一步能让你分清「路由拦住」和「代码没找到」。
  4. 故意删掉 [FromBody],POST 一条数据,观察服务端拿到的字段值。再把它加回去,对比结果。
  5. 把 app.UseAuthorization() 移到 app.MapGet 之后,给一个端点加 RequireAuthorization,不带任何凭据请求它。第 4 篇会解释为什么它变成了匿名可访问。

小结

下一篇讲数据访问。上面两个写法都在用 AppDb,但 DbContext 是 scoped 的,一个请求一个实例,把它注入到单例里、或者跨请求缓存起来,都会出问题;EnsureCreated 也只适合演示,正式项目要换成迁移。这些坑在第 2 篇里只是「能跑」,第 3 篇才会拆开。

这篇的三句话总结:第一,路由模板里的约束在进入处理函数之前就生效,404 不一定是代码没写,可能是路由层拦下了;第二,中间件顺序就是注册顺序,UseRouting、UseAuthentication、UseAuthorization 三步顺序错了不会报错,只会让鉴权静默失效;第三,minimal API 和 Controller 能共存,但路径必须分开,团队规模超过四个人、端点超过五十个、或者依赖成熟过滤器生态时,Controller 更划算。