MapGroup 是组织 Minimal API 路由的标准做法，解决硬编码路径导致的前缀维护难、中间件/授权无法统一、OpenAPI 归属不清及拼接错误等问题，必须在 app.Build() 后调用，并支持链式配置授权与过滤器。
MapGroup 是组织 Minimal API 路由最直接、最安全的方式，不是“可选技巧”，而是解决路由散乱、前缀重复、权限策略不统一等问题的**标准做法**。
为什么不能直接拼接字符串写 MapGet("/api/users/list")？
路径硬编码会导致三类问题：一是改前缀要全局搜索替换；二是无法为整组端点统一加中间件或授权；三是 Swagger 或 OpenAPI 文档里看不出逻辑归属。更隐蔽的问题是：当多个端点共享 /api/v1 前缀时，手动拼接容易漏掉斜杠（比如写成 "/api/v1users"），而 MapGroup 会自动处理路径拼接与规范化。
MapGroup 必须在 app 上调用，不能在 builder 上
MapGroup 是 IEndpointRouteBuilder 的扩展方法，属于运行时路由注册阶段，必须在 var app = builder.Build() 之后使用。常见错误是把它写在 builder.Services 配置块里，结果编译报错：“IWebHostBuilder does not contain a definition for MapGroup”。正确位置如下：
var builder = WebApplication.CreateBuilder(args);
// ... 注册服务
var app = builder.Build();
// ✅ 正确：在 app 上调用
var usersGroup = app.MapGroup("/api/users");
usersGroup.MapGet("/", () => Results.Ok());
usersGroup.MapGet("/{id:long}", (long id) => Results.Ok(id));
app.Run();
如何给 MapGroup 统一加授权和日志中间件？
MapGroup 返回的是 IEndpointConventionBuilder，支持链式调用 RequireAuthorization()、AddEndpointFilter() 等，所有子端点自动继承。注意两点：
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
-
RequireAuthorization()依赖app.UseAuthorization()已注册，否则 401/403 不生效 - 自定义 EndpointFilter（如日志）需用
AddEndpointFilter<MyLoggingFilter>()，不能直接传 lambda —— 因为 filter 实例生命周期由 DI 管理，lambda 无法注入依赖 - 若只对部分子端点跳过授权，得在具体
MapGet后调用AllowAnonymous()
示例：
var adminGroup = app.MapGroup("/admin")
.RequireAuthorization("AdminPolicy")
.AddEndpointFilter<AuditEndpointFilter>();
adminGroup.MapGet("/stats", () => Results.Ok())
.AllowAnonymous(); // 这个例外放行
嵌套路由和 MapFallback 容易被忽略的边界
当需要捕获 /dashboard/{*path} 这类通配路径时，别直接用 MapGet("/dashboard/{*path}") —— 它不会匹配静态文件（如 /dashboard/index.html），且可能干扰其他中间件。应改用 MapFallback：
app.MapGroup("/dashboard")
.MapFallback(async (HttpContext context) =>
{
// 手动检查是否为静态资源，否则返回 SPA 入口
if (context.Request.Path.StartsWithSegments("/dashboard/static"))
return await Results.File("wwwroot/dashboard/static/app.js").ExecuteAsync(context);
return Results.File("wwwroot/dashboard/index.html");
});
关键点：MapFallback 是最后兜底的匹配器，它不参与常规路由优先级排序；一旦用了，就得自己处理所有路径逻辑，包括 MIME 类型、缓存头、甚至 404 判定——这点常被低估。
MapGroup，而是决定哪些端点该进同一组、哪些策略必须强绑定、以及 fallback 里要不要做重定向而非直接返回文件。这些判断没标准答案，得看你的 API 边界是否清晰、前端是否单页、权限模型是否分层。 
