Node.js/Go 后端架构：中间件模式与请求管道的工程实践

一、请求处理的散乱现状：为什么每个接口都在重复写日志、鉴权和限流

在后端服务开发中，每个 HTTP 请求都需要经过认证鉴权、参数校验、日志记录、限流熔断、错误处理等横切关注点。如果将这些逻辑直接写在业务处理函数中，代码会迅速膨胀为"千行函数"，且同一逻辑在不同接口间反复复制。中间件模式的核心价值在于：将横切关注点从业务逻辑中解耦，以可组合的管道形式串联处理，实现"一次编写，处处生效"。

二、中间件管道的执行模型：洋葱模型与责任链

中间件管道的经典执行模型是洋葱模型（Onion Model）：请求从外层中间件逐层向内传递，到达业务处理函数后，响应再从内层逐层向外返回。每一层中间件都可以在请求进入时执行前置逻辑（如鉴权、日志），在响应返回时执行后置逻辑（如耗时统计、错误上报）。

graph LR
    A[请求] --> B[限流中间件]
    B --> C[认证中间件]
    C --> D[日志中间件]
    D --> E[参数校验中间件]
    E --> F[业务处理函数]
    F --> G[响应]
    G --> E
    E --> D
    D --> C
    C --> B
    B --> H[客户端]

    style B fill:#ffcdd2
    style C fill:#fff9c4
    style D fill:#c8e6c9
    style E fill:#bbdefb
    style F fill:#e1bee7

Go 语言的中间件实现基于 http.Handler 接口的函数包装，Node.js（Express/Koa）则基于回调或 async/await 的函数组合。两者的核心差异在于错误传播机制：Go 通过显式的 error 返回值传播错误，Node.js 通过 next(err) 或 try-catch 传播异常。

三、中间件管道的生产级实现

3.1 Go 中间件管道

package middleware

import (
	"context"
	"log/slog"
	"net/http"
	"time"
)

// Middleware 定义中间件类型：接收下一个 Handler，返回包装后的 Handler
type Middleware func(http.Handler) http.Handler

// Chain 将多个中间件组合为管道，按传入顺序从外到内执行
func Chain(middlewares ...Middleware) Middleware {
	return func(final http.Handler) http.Handler {
		for i := len(middlewares) - 1; i >= 0; i-- {
			final = middlewares[i](final)
		}
		return final
	}
}

// RateLimit 令牌桶限流中间件
func RateLimit(rps int, burst int) Middleware {
	// 使用 golang.org/x/time/rate 实现令牌桶
	// 此处简化为计数器限流，展示中间件结构
	type limiter struct {
		count    int
		lastTime time.Time
	}

	limiters := make(map[string]*limiter)

	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			key := r.RemoteAddr
			now := time.Now()

			if l, exists := limiters[key]; exists {
				if now.Sub(l.lastTime) < time.Second && l.count >= rps {
					http.Error(w, "请求过于频繁，请稍后重试", http.StatusTooManyRequests)
					return
				}
				if now.Sub(l.lastTime) >= time.Second {
					l.count = 0
					l.lastTime = now
				}
				l.count++
			} else {
				limiters[key] = &limiter{count: 1, lastTime: now}
			}

			next.ServeHTTP(w, r)
		})
	}
}

// Auth JWT 认证中间件
func Auth(secret string) Middleware {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			token := r.Header.Get("Authorization")
			if token == "" {
				http.Error(w, "缺少认证令牌", http.StatusUnauthorized)
				return
			}

			// 解析 JWT 并注入用户信息到 context
			claims, err := parseJWT(token, secret)
			if err != nil {
				http.Error(w, "认证令牌无效", http.StatusUnauthorized)
				return
			}

			// 将用户信息注入请求上下文，下游处理器可直接读取
			ctx := context.WithValue(r.Context(), "user_id", claims.UserID)
			ctx = context.WithValue(ctx, "user_role", claims.Role)
			next.ServeHTTP(w, r.WithContext(ctx))
		})
	}
}

// Logger 请求日志中间件：记录请求方法、路径、耗时和状态码
func Logger() Middleware {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			start := time.Now()

			// 包装 ResponseWriter 以捕获状态码
			wrapped := &responseWriter{ResponseWriter: w, statusCode: http.StatusOK}

			next.ServeHTTP(wrapped, r)

			slog.Info("请求处理完成",
				"method", r.Method,
				"path", r.URL.Path,
				"status", wrapped.statusCode,
				"duration", time.Since(start).String(),
				"remote_addr", r.RemoteAddr,
			)
		})
	}
}

// responseWriter 包装 http.ResponseWriter，捕获写入的状态码
type responseWriter struct {
	http.ResponseWriter
	statusCode int
}

func (rw *responseWriter) WriteHeader(code int) {
	rw.statusCode = code
	rw.ResponseWriter.WriteHeader(code)
}

// 使用示例：组合中间件管道
func SetupRoutes(mux *http.ServeMux, jwtSecret string) {
	pipeline := Chain(
		Logger(),
		RateLimit(100, 20),
		Auth(jwtSecret),
	)

	mux.Handle("/api/users", pipeline(http.HandlerFunc(listUsers)))
	mux.Handle("/api/orders", pipeline(http.HandlerFunc(listOrders)))
}

3.2 Node.js 中间件管道（Koa 风格）

// src/middleware/pipeline.ts
import { Context, Next } from "koa";

type Middleware = (ctx: Context, next: Next) => Promise<void>;

/**
 * 请求限流中间件：基于令牌桶算法
 * 设计考量：限流应在认证之前执行，避免未认证请求消耗认证服务资源
 */
export function rateLimit(rps: number, burst: number): Middleware {
  const buckets = new Map<string, { tokens: number; lastRefill: number }>();

  return async (ctx: Context, next: Next) => {
    const key = ctx.ip;
    const now = Date.now();
    const bucket = buckets.get(key) || { tokens: burst, lastRefill: now };

    // 补充令牌
    const elapsed = (now - bucket.lastRefill) / 1000;
    bucket.tokens = Math.min(burst, bucket.tokens + elapsed * rps);
    bucket.lastRefill = now;

    if (bucket.tokens < 1) {
      ctx.status = 429;
      ctx.body = { error: "请求过于频繁，请稍后重试" };
      return;
    }

    bucket.tokens -= 1;
    buckets.set(key, bucket);
    await next();
  };
}

/**
 * 请求日志中间件：记录请求耗时与状态码
 * 设计考量：日志中间件应置于管道最外层，确保所有请求（包括被限流的）都被记录
 */
export function requestLogger(): Middleware {
  return async (ctx: Context, next: Next) => {
    const start = Date.now();
    await next();
    const duration = Date.now() - start;

    console.log(JSON.stringify({
      method: ctx.method,
      path: ctx.path,
      status: ctx.status,
      duration_ms: duration,
      ip: ctx.ip,
    }));
  };
}

/**
 * 错误恢复中间件：捕获下游所有异常，统一错误响应格式
 * 设计考量：必须置于管道最外层，确保任何未捕获的异常都能被兜底处理
 */
export function errorRecovery(): Middleware {
  return async (ctx: Context, next: Next) => {
    try {
      await next();
    } catch (error: any) {
      ctx.status = error.status || 500;
      ctx.body = {
        error: error.expose ? error.message : "服务内部错误",
        request_id: ctx.state.requestId,
      };
      // 非暴露错误记录完整堆栈，便于排查
      if (!error.expose) {
        console.error(`[ERROR] ${ctx.method} ${ctx.path}:`, error);
      }
    }
  };
}

四、中间件管道的边界与权衡

中间件管道的最大风险是执行顺序依赖。认证中间件必须在业务逻辑之前执行，限流中间件应在认证之前（否则未认证请求会消耗认证资源），日志中间件应在最外层（确保所有请求都被记录）。一旦顺序错误，可能导致未认证请求绕过鉴权或限流失效。团队必须建立明确的中间件注册规范，而非依赖开发者自行排列。

其次是上下文污染。中间件通过 Context 传递数据（如用户 ID、请求 ID），但 Context 是一个无类型的字典，键名冲突或类型断言失败会导致运行时错误。Go 的 context.WithValue 缺乏类型安全，Node.js 的 ctx.state 同样如此。生产环境建议定义类型化的上下文访问函数，而非直接读写 Context。

在性能方面，每层中间件都引入一次函数调用开销。对于高吞吐场景（如每秒万级请求），10 层中间件的调用链可能增加 0.5-1ms 的延迟。虽然绝对值不大，但在 P99 延迟敏感的场景下需要评估。可以通过合并低价值中间件（如将日志与请求 ID 合并为一层）来减少调用深度。

五、总结

中间件模式通过洋葱模型的管道组合，将横切关注点从业务逻辑中解耦，实现了认证、限流、日志、错误处理等逻辑的复用与统一管理。落地时需注意：严格定义中间件执行顺序，避免安全漏洞；用类型化访问函数替代裸 Context 读写，防止键名冲突与类型错误；评估中间件深度对 P99 延迟的影响，必要时合并低价值中间件。中间件模式适用于所有 HTTP 服务，但需警惕过度拆分导致的调用链过长和调试困难。