📚 课程目录第2章 Go中间件设计模式

2. Go中间件设计模式：HTTP中间件链、Handler接口、Next函数、Context传递

在构建OAuth2.0回调验证与错误处理链路时，中间件设计模式是核心骨架。Go标准库 net/http 提供了简洁的接口，而社区在此基础上演化出链式组合、Next调度与Context传递三大机制。理解这三者，才能写出可复用、可测试的中间件链路。

2.1 核心接口：http.Handler

一切中间件的起点是 http.Handler 接口。它只定义一个方法：

type Handler interface {
    ServeHTTP(ResponseWriter, *Request)
}

任何实现了该接口的类型都可以作为HTTP处理器。中间件本质上是一个接收 Handler 并返回新 Handler 的函数，即 func(http.Handler) http.Handler。这种模式允许将多个处理层嵌套组合。

概念	说明	示例
Handler接口	所有HTTP处理器的统一契约	`type Handler interface { ServeHTTP(...) }`
中间件函数签名	接收Handler，返回Handler	`func(next http.Handler) http.Handler`
适配器	将普通函数转为Handler	`http.HandlerFunc(fn)`

2.2 中间件链：洋葱模型与Next函数

多个中间件按顺序嵌套，形成“洋葱”结构。每个中间件内部调用 next.ServeHTTP(w, r) 将请求传递给下一个处理器。这个调用点就是 Next函数 的语义——它控制请求何时进入下一层，以及响应何时返回上一层。

  关键设计点： 中间件可以在调用 next 之前执行前置逻辑（如日志、鉴权），也可以在 next 返回后执行后置逻辑（如响应头修改、错误捕获）。next 不调用，则请求被“短路”，后续中间件不会执行。

// 日志中间件示例
func LoggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 前置逻辑
        log.Printf("Request: %s %s", r.Method, r.URL.Path)

        // 调用下一个处理器
        next.ServeHTTP(w, r)

        // 后置逻辑
        log.Printf("Response sent for %s", r.URL.Path)
    })
}

链式组合通常通过一个辅助函数实现：

// Chain 将多个中间件组合成一个
func Chain(handler http.Handler, middlewares ...func(http.Handler) http.Handler) http.Handler {
    for i := len(middlewares) - 1; i >= 0; i-- {
        handler = middlewares[i](handler)
    }
    return handler
}

// 使用
finalHandler := Chain(
    myOAuthHandler,
    LoggingMiddleware,
    RecoveryMiddleware,
    RateLimitMiddleware,
)

2.3 Context传递：请求级数据共享

中间件链中，每个环节都可能需要共享数据（如用户身份、追踪ID、错误状态）。Go 1.7+ 的 context.Context 是官方推荐的传递方式，通过 r.Context() 获取，使用 context.WithValue 派生新context，再通过 r.WithContext() 替换请求的context。

注意： context.Value 应仅用于请求范围的数据，如认证信息、请求ID。不要用它传递可选参数或替代函数参数。键类型应使用自定义类型，避免string冲突。

// 定义context键类型（避免冲突）
type contextKey string

const UserKey contextKey = "user"

// 认证中间件：将用户信息注入context
func AuthMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        token := r.Header.Get("Authorization")
        user, err := validateToken(token)
        if err != nil {
            http.Error(w, "Unauthorized", http.StatusUnauthorized)
            return
        }
        // 派生新context并注入用户信息
        ctx := context.WithValue(r.Context(), UserKey, user)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// 后续处理器从context读取用户信息
func MyHandler(w http.ResponseWriter, r *http.Request) {
    user := r.Context().Value(UserKey).(User)
    // 使用user信息处理请求
}

2.4 三种模式对比

模式	核心机制	典型用途	注意事项
Handler接口	ServeHTTP(ResponseWriter, *Request)	所有HTTP处理器的统一抽象	必须实现ServeHTTP方法
Next函数	显式调用 next.ServeHTTP(w, r)	控制请求流转、短路、后置处理	不调用next则链路终止
Context传递	context.WithValue + r.WithContext	请求级数据共享（用户、追踪、超时）	键类型需自定义，避免string

2.5 在OAuth2.0回调验证中的应用

在OAuth2.0回调链路中，中间件模式可以这样组织：

恢复中间件：捕获panic，防止回调处理崩溃导致服务不可用。
日志中间件：记录回调请求的state、code参数。
CSRF校验中间件：验证state参数与session中的值是否匹配。
令牌交换中间件：用code向授权服务器换取access_token，将token注入context。
用户信息中间件：用access_token获取用户信息，注入context。
最终处理器：从context读取用户信息，完成登录或注册。

最佳实践： 每个中间件只关注一个职责。错误处理应集中在恢复中间件或专门的错误中间件中，避免每个中间件都重复编写错误响应逻辑。

2.6 设计原则总结

单一职责：每个中间件只做一件事，如日志、鉴权、限流。
无侵入：中间件不应修改请求或响应的结构，除非通过context传递数据。
可组合：中间件顺序应可配置，且不依赖特定顺序（除依赖关系外）。
错误传播：错误应通过context或自定义错误类型向上传递，避免在中间件内部直接写响应。
测试友好：中间件应接受 http.Handler 并返回 http.Handler，便于单元测试时传入mock处理器。