中间件

背景与问题界定 中间件（Middleware）是 Node.js Web 框架最核心的架构模式。从 Express 的线性链式调用到 Koa 的洋葱模型（Onion Model），中间件的组织方式深刻影响着应用的执行流程、错误处理和扩展能力。许多开发者在日常使用中只是简单地调用 app.use(fn)，却没有深入理解中间件的执行顺序、异步模型和错误传播机制。由此导致的问题包括：静态文件中间件与路由中间件的顺序颠导致 404 错误；错误处理中间件未正确放置导致异常被吞没；在 Koa 中使用 async/await 但漏写 next 导致的执行链断裂。理解并设计一套健壮的中间件体系，是构建稳定 Node.js 服务的基础。 目标拆解与工程约束 中间件顺序决定了执行流程：请求处理链的顺序由中间件注册顺序决定，任何顺序错误都可能导致功能异常，必须提供清晰的顺序规范文档。 错误处理中间件必须为最后一个中间件：Express 中错误处理中间件有 4 个参数 (err, req, res, next)；Koa 中通过在 catch 中捕获，两者均要求错误处理在最后注册。 异步中间件的正确率处理：async 中间件函数中的未捕获异常必须通过框架的错误处理渠道传播，不应使用全局的 process.on('unhandledRejection') 兜底。 中间件的生命周期与资源清理：中间件可能分配的资源（数据库连接、文件句柄、计时器）应在中间件执行完毕或请求结束时释放，避免资源泄漏。 方案设计 Express 的中间件体系是线性的：请求按注册顺序依次通过每个中间件，遇到响应终止则停止传递。这种模型简单直观，但存在两个局限：一是无法在响应发出后执行后置逻辑（如记录响应时间）；二是错误处理只能通过跳到 4 参数的错误中间件来处理。 Koa 的洋葱模型通过 async/await 和 next 函数实现了双向的执行流程。请求从外层中间件进入，经过 await next() 到达内层中间件，响应从内层逐步返回到外层： // Koa 洋葱模型示意图 app.use(async (ctx, next) => { console.log('① 进入外层中间件') await next() console.log('⑥ 返回外层中间件 - 响应后置处理') }) app.use(async (ctx, next) => { console.log('② 进入中层中间件') await next() console.log('⑤ 返回中层中间件') }) app.use(async (ctx) => { console.log('③ 进入内层中间件（路由处理）') ctx.body = { message: 'Hello' } console.log('④ 返回内层中间件') }) // 输出顺序: ① ② ③ ④ ⑤ ⑥ 这种模型的优势在于：请求前和响应后的逻辑可以自然地写在 await next() 上下两侧。日志记录、性能计时、事务管理等功能只需要一个中间件即可覆盖请求全生命周期。 ...

背景与问题界定 在一个由20+微服务组成的平台上，每个服务都重复实现着相同的基础功能——请求日志、鉴权、限流、超时控制、错误恢复。这些功能的实现方式各不相同：有的放在Handler中作为第一行代码调用，有的封装在装饰器函数中，有的甚至分散在业务逻辑中。当需要新增一个全链路的安全审计功能时，开发者需要在所有服务中逐个修改——这不仅是效率问题，更是质量隐患。 中间件模式（Middleware Pattern）是解决这类横切关注点（Cross-cutting Concerns）的经典模式。在Go生态中，无论是HTTP（net/http、gin、echo）还是gRPC（grpc.UnaryServerInterceptor），都原生支持中间件链。但工程化的挑战在于：如何设计一致的中间件接口，使得HTTP和gRPC的中间件可以复用？如何管理中间件的执行顺序？如何在中间件中注入并传递链路追踪信息？这些问题在实践中往往比"如何写一个中间件"要复杂得多。 目标拆解与工程约束 HTTP和gRPC中间件需要统一抽象：尽管两者的Handler签名不同（http.Handler vs grpc.UnaryHandler），但核心模式都是"洋葱模型"——请求依次经过中间件链到达业务Handler，响应反向传播。需要抽象出一套通用的Middleware接口，减少学习成本。 中间件执行顺序必须清晰可配：日志应该在鉴权之前还是之后？限流在鉴权之前还是之后？不同的场景有不同的顺序要求。中间件链的构建方式必须支持调整顺序且保证可读性。 性能开销严格可控：每个中间件都在请求热路径上执行，额外开销不能超过特定预算。例如，日志中间件不应序列化整个请求体，限流中间件不应执行数据库查询。 链路追踪必须穿透中间件边界：中间件是追踪信息的天然采集点——每个中间件在请求经过时可以记录时间戳和状态。追踪数据需要通过context.Context从入站传播到出站，并随RPC调用传递到下游服务。 方案设计 核心方案围绕"洋葱模型"的工程化封装。首先定义统一中间件接口： type Middleware func(Handler) Handler type Handler func(ctx context.Context, req any) (resp any, err error) 基于这个接口，同时适配HTTP和gRPC。HTTP适配器将标准http.Handler转换为统一Handler，gRPC适配器将grpc.UnaryServerInterceptor转换为统一Middleware： // HTTP适配 func HTTPAdapter(h http.Handler) Handler { return func(ctx context.Context, req any) (any, error) { h.ServeHTTP(ctx.Value("http").(http.ResponseWriter), req.(*http.Request)) return nil, nil } } // gRPC适配 func GRPCInterceptor(m Middleware) grpc.UnaryServerInterceptor { return func(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) { adaptedHandler := Handler(func(ctx context.Context, req any) (any, error) { return handler(ctx, req) }) return m(adaptedHandler)(ctx, req) } } 链路追踪中间件是利用中间件模式实现可观测性的最佳范例。它在请求入口处注入trace ID，在请求通过其他中间件时记录span，并在请求结束时上报追踪数据： func TracingMiddleware(serviceName string) Middleware { return func(next Handler) Handler { return func(ctx context.Context, req any) (any, error) { // 从请求头提取或创建trace ID traceID := extractTraceID(ctx) span := tracer.StartSpan(serviceName, trace.WithSpanKind(trace.SpanKindServer)) defer span.End() ctx = trace.ContextWithSpan(ctx, span) resp, err := next(ctx, req) // 记录错误信息 if err != nil { span.RecordError(err) } return resp, err } } } 恢复中间件在生产环境中同样关键，它捕获业务Handler中未处理的panic，记录完整的调用栈，并返回友好的错误响应： ...