应封装为 IEndpointRouteBuilder 扩展方法，避免重复注册；路由逻辑需延迟获取服务、统一用 MapGroup 管理前缀、支持配置化参数，禁止在扩展中注册服务或条件添加路由。
为什么不能直接在 Program.cs 里重复写 MapGet/MapPost
Minimal API 的路由注册本质是调用 IEndpointRouteBuilder 上的扩展方法（如 MapGet、MapPost），这些方法返回 IEndpointConventionBuilder，本身不支持“复用一组路由逻辑”。如果把相同路由逻辑复制粘贴到多个 WebApplication 实例或不同环境分支里，会立刻面临维护断裂：改一个接口要同步改三处，漏掉一处就出错。
封装成 IEndpointRouteBuilder 扩展方法是最小侵入方案
核心思路是把路由注册逻辑抽成 IEndpointRouteBuilder 的扩展方法，让调用方只写一行代码就能挂载整套功能。它不依赖 DI 容器初始化顺序，不强制要求特定服务注册，也不污染 Program.cs 主流程。
常见错误现象：System.InvalidOperationException: No service for type 'MyApp.Features.User.IUserService' has been registered. —— 这说明你在扩展方法里提前 Resolve 了服务，但此时 DI 容器还没 Build。
正确做法是只注册路由，把服务获取推迟到 handler 执行时（即用 context.RequestServices.GetRequiredService<t>()</t>）：
public static class UserEndpoints
{
public static void MapUserEndpoints(this IEndpointRouteBuilder endpoints)
{
var group = endpoints.MapGroup("/api/users");
<pre class="brush:php;toolbar:false;"> group.MapGet("/", async (HttpContext context) =>
{
var service = context.RequestServices.GetRequiredService<IUserService>();
var users = await service.GetAllAsync();
return Results.Ok(users);
});
group.MapGet("/{id:long}", async (HttpContext context, long id) =>
{
var service = context.RequestServices.GetRequiredService<IUserService>();
var user = await service.GetByIdAsync(id);
return user is null ? Results.NotFound() : Results.Ok(user);
});
}}
- 所有 handler 都用
HttpContext参数，避免在扩展方法里调用app.Services - 路径前缀统一用
MapGroup管理，比拼接字符串更安全 - 不要在扩展方法里调用
AddScoped或ConfigureServices，那是WebApplicationBuilder的职责
如何支持可配置的路由前缀和授权策略
硬编码 /api/users 无法适配 BFF 层或租户隔离场景。扩展方法应接受配置参数，但注意：不能传入 IConfiguration 实例（生命周期冲突），而应传入普通字符串或配置对象。
示例：支持自定义前缀 + 可选授权策略名
public static void MapUserEndpoints(
this IEndpointRouteBuilder endpoints,
string prefix = "/api/users",
string? policy = null)
{
var group = endpoints.MapGroup(prefix);
<pre class="brush:php;toolbar:false;">if (!string.IsNullOrEmpty(policy))
group.RequireAuthorization(policy);
group.MapGet("/", async (HttpContext ctx) => { /* ... */ });
// 其他路由...}
- 调用时可写
app.MapUserEndpoints("/v2/users", "AdminOnly") - 策略名必须已在
AddAuthorization中预注册，否则运行时报InvalidOperationException: The authorization policy named 'xxx' was not found. - 避免在扩展方法里做条件判断是否添加某条路由（比如“仅开发环境注册调试端点”），那会让路由表在不同环境不一致，CI/CD 易出问题
重用时要注意中间件顺序和终结点分组语义
Minimal API 的终结点是按注册顺序匹配的，MapGroup 生成的终结点共享同一组路由约束和元数据。如果你在两个扩展方法里都用了 MapGroup("/api")，它们会合并进同一个分组；但如果先调用 A.MapX() 再调用 B.MapY()，而 B 里有更宽泛的通配符路由（如 MapGet("/{**slug}")），就会拦截本该由 A 处理的请求。
容易被忽略的点：
-
MapGroup不是命名空间隔离，而是路由树节点，重复前缀不会报错但可能覆盖行为 - 跨项目重用扩展方法时，确保目标项目已引用对应程序集且未禁用隐式使用（
<implicitusings>enable</implicitusings>） - 若扩展方法中用了
WithMetadata（如AllowAnonymous），记得导入Microsoft.AspNetCore.Authorization命名空间，否则编译通过但运行时授权失效
