ASP.NET Core中间件顺序决定逻辑生效，必须正确注册UseAuthentication、UseAuthorization等；InvokeAsync签名需严格匹配；Map分支需独立终结；读取请求体前须EnableBuffering并重置Position。
自定义中间件管道不是“拼一堆Use就行”，顺序错、漏await next()、或Map分支里误用next，会导致请求静默卡死或响应不完整——这不是报错，而是根本没走到你预期的位置。
中间件注册顺序为什么直接决定逻辑是否生效
ASP.NET Core 不校验顺序合理性，只机械执行代码中 app.UseXXX() 的排列。比如：
-
app.UseAuthentication()必须在app.UseAuthorization()之前，否则User.Identity.IsAuthenticated始终为false - 日志中间件若注册在
app.UseExceptionHandler()之后，就捕获不到未处理异常 -
app.UseStaticFiles()放在app.UseRouting()之后但没加app.UseEndpoints()，静态文件请求会被路由中间件拦截并返回 404
调试时可在每个中间件开头加 Console.WriteLine($"[{nameof(MyMiddleware)}] enter")，看是否成对出现；只看到 enter 没 exit，基本就是顺序或 await 问题。
UseMiddleware() 中 InvokeAsync 方法签名必须严格匹配
框架靠反射找入口方法，任何偏差都会抛 InvalidOperationException: No public Invoke or InvokeAsync method found：
- 方法名必须是
InvokeAsync（不能是Invoke或Handle） - 必须是
public async Task返回类型（即使内部没 await，也不能用 void 或同步 Task） - 第一个参数必须是
HttpContext context，不能缺，不能换名 - 后续参数如
ILogger<MyMiddleware> logger会由 DI 自动注入，但不能出现在构造函数以外的其他位置（比如不能塞进 InvokeAsync 的第三个参数再手动 new）
正确示例：
public class RequestLoggingMiddleware
{
private readonly RequestDelegate _next;
public RequestLoggingMiddleware(RequestDelegate next, ILogger<RequestLoggingMiddleware> logger)
{
_next = next;
// logger 已注入，可存为字段或直接用
}
public async Task InvokeAsync(HttpContext context, ILogger<RequestLoggingMiddleware> logger)
{
logger.LogInformation("Request started");
await _next(context); // 必须 await
logger.LogInformation("Request completed");
}
}
Map 分支里的 next 不指向主管道，而是当前分支末端
app.Map("/api", branch => { ... }) 创建的是隔离子管道，branch.Use(...) 中的 next 只串联该分支内中间件，不会自动跳回主流程。常见错误：
- 在 Map 内部调用
app.Use(...)—— 这会注册到主管道，不是分支里 - 分支末尾忘了
branch.Run(...)，导致整个分支无终结点，请求卡住 - 分支中间件里写了
await next(context)却没配Run，等价于短路，客户端收不到响应
分支内要确保有且仅有一个终结点：要么 branch.Run(async ctx => { ... })，要么 branch.UseEndpoints(...)，不能靠主管道的 app.Run() 补救。
读取请求体前必须 EnableBuffering，否则后续模型绑定失败
HTTP 请求体只能被读一次。如果中间件想记录原始 JSON（比如审计日志），又不想影响 Controller 的 [FromBody] 绑定，必须提前启用缓冲：
- 漏掉
context.Request.EnableBuffering()→ 后续StreamReader读完后，MVC 模型绑定拿不到内容，参数为 null - 启用后还要重置指针：
context.Request.Body.Position = 0;，否则 StreamReader 从末尾开始读，得到空内容 - 缓冲会占用内存，生产环境慎用于大文件上传场景
典型写法：
await context.Request.EnableBuffering(); using var reader = new StreamReader(context.Request.Body); var body = await reader.ReadToEndAsync(); context.Request.Body.Position = 0; // 重置位置供后续使用
最常被忽略的其实是 await next(context) 的执行时机：它既是请求阶段的终点，也是响应阶段的起点。修改 Response.StatusCode 必须在它之前，读取 StatusCode 必须在它之后——这个分水岭一旦错位，状态码就永远不对。
