中间件必须实现InvokeAsync或Invoke方法；需通过UseMiddleware()注册于管道中，构造函数注入依赖，短路时须显式设StatusCode和ContentType。
中间件必须实现 Invoke 或 InvokeAsync 方法
ASP.NET Core 中间件本质是一个接收 HttpContext 并返回 Task 的类型。框架只认两个约定方法名：Invoke（同步）或更推荐的 InvokeAsync（异步）。如果方法名拼错、签名不匹配（比如漏掉 HttpContext 参数，或返回值不是 Task），运行时不会报编译错误，但请求会直接 500，日志里常出现 System.InvalidOperationException: No method 'Invoke' or 'InvokeAsync' found。
实操建议：
- 始终用
public async Task InvokeAsync(HttpContext context)，避免同步阻塞 - 必须调用
await _next(context)（除非明确要终止管道，如认证失败后直接写响应） - 不要在中间件类里定义无参构造函数——框架通过 DI 解析，依赖项全靠构造函数注入
注册中间件要用 UseMiddleware() ，不是 AddSingleton
中间件不是普通服务，不能通过 services.AddSingleton 注册。它必须在 Startup.Configure(IApplicationBuilder app) 或 Program.cs 的管道配置中显式挂载，且顺序决定执行时机。
常见错误：
- 把中间件当服务注册进
IServiceCollection—— 框架完全忽略，也不会报错 - 在
app.UseRouting()之后才调用app.UseMiddleware，导致路由未解析，() context.Request.RouteValues为空 - 把
UseMiddleware放在UseEndpoints之后 —— 中间件根本收不到进入 endpoint 的请求
正确顺序示例（简化）：
app.UseRouting(); app.UseAuthentication(); // 内置中间件 app.UseMiddleware(); // 自定义中间件 app.UseEndpoints(endpoints => { ... });
带依赖的中间件必须通过构造函数注入，不能手动 new
如果中间件需要 IConfiguration、ILogger 或自定义服务（如 IDatabaseService），只能通过构造函数声明，由 DI 容器自动提供。手动 new LoggingMiddleware(...) 会导致依赖无法解析，抛出 InvalidOperationException: Unable to resolve service for type 'ILogger`1[LoggingMiddleware]'。
示例写法：
public class LoggingMiddleware
{
private readonly RequestDelegate _next;
private readonly ILogger _logger;
public LoggingMiddleware(RequestDelegate next, ILogger logger)
{
_next = next;
_logger = logger;
}
public async Task InvokeAsync(HttpContext context)
{
_logger.LogInformation("Request: {Method} {Path}", context.Request.Method, context.Request.Path);
await _next(context);
}
}
注意：RequestDelegate 是必需参数，代表管道中的下一个中间件，框架强制要求它作为第一个构造参数。
短路中间件要手动设置响应状态码和内容类型
像权限校验、API 版本拒绝这类中间件，常需提前结束请求（即“短路”）。此时不能只写 context.Response.WriteAsync("Forbidden") 就完事——默认响应头是空的，浏览器可能因缺少 Content-Type 渲染异常，HTTP 状态码也还是 200。
必须显式设置：
context.Response.StatusCode = StatusCodes.Status403Forbidden-
context.Response.ContentType = "application/json"（或text/plain） - 确保在
WriteAsync前设置，否则可能被后续中间件覆盖
否则你会看到响应体是 JSON 字符串，但状态码是 200，前端判断逻辑全乱。
中间件的生命周期和执行顺序比表面看起来更敏感，尤其是依赖注入时机和管道位置——这两处出问题，往往没有明显报错，只有请求静默失败或行为错乱。
