📚 课程目录第3章 HTTP中间件基础

3. HTTP 中间件基础：Go 标准库 net/http 处理流程、中间件模式、编写第一个权限验证中间件

3.1 Go 标准库 net/http 核心处理流程

在深入中间件之前，必须理解 Go 标准库 net/http 处理 HTTP 请求的完整链路。Go 的 HTTP 服务器采用 Handler 接口 作为核心抽象，任何实现了 ServeHTTP(ResponseWriter, *Request) 方法的类型都可以作为处理器。

核心接口定义：

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

标准库的请求处理流程分为四个阶段：

阶段	组件	职责
1. 监听与连接	`net.Listener`	监听 TCP 端口，接受新连接
2. 协议解析	`http.Server`	读取连接数据，解析 HTTP 请求行、头部、体
3. 路由分发	`http.ServeMux`	根据请求路径匹配注册的 Handler
4. 业务处理	自定义 Handler	执行具体业务逻辑，写入响应

默认的 http.ServeMux 是简单的路径匹配器，不支持路径参数、HTTP 方法路由等高级特性，但作为中间件学习的起点足够清晰。

3.2 中间件模式：函数式组合与链式调用

HTTP 中间件本质上是一个 包装函数：它接收一个 http.Handler，返回一个新的 http.Handler，在调用原始 Handler 前后插入横切逻辑。Go 中最常见的中间件签名有两种：

模式	签名	适用场景
函数式	`func(http.Handler) http.Handler`	标准中间件，可任意组合
结构体式	`type Middleware struct { ... }`	需要依赖注入（如数据库、配置）

函数式中间件的核心模式如下：

// 中间件类型定义
type Middleware func(http.Handler) http.Handler

// 链式组合函数
func Chain(handler http.Handler, middlewares ...Middleware) http.Handler {
    for i := len(middlewares) - 1; i >= 0; i-- {
        handler = middlewares[i](handler)
    }
    return handler
}

// 使用示例
func main() {
    finalHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello, World!"))
    })

    // 按顺序执行：Logger -> Auth -> finalHandler
    chained := Chain(finalHandler, LoggerMiddleware, AuthMiddleware)
    http.Handle("/api", chained)
    http.ListenAndServe(":8080", nil)
}

组合顺序规则： 中间件数组中的第一个中间件是最外层包装，最后一个中间件最靠近业务 Handler。执行顺序与注册顺序相同，但调用链是嵌套的。

中间件的典型职责包括：

日志记录：记录请求方法、路径、状态码、耗时
权限验证：检查 Token、Session、API Key
请求限流：基于 IP 或用户进行速率限制
请求/响应转换：统一 JSON 格式、CORS 头、压缩
错误恢复：捕获 panic，返回 500 而非崩溃

3.3 编写第一个权限验证中间件

现在我们将理论付诸实践，编写一个基于 Bearer Token 的权限验证中间件。该中间件从请求头中提取 Token，验证其有效性，如果无效则直接返回 401 并阻止后续处理。

3.3.1 基础实现

package middleware

import (
    "net/http"
    "strings"
)

// AuthMiddleware 验证 Bearer Token
func AuthMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 1. 从 Authorization 头提取 Token
        authHeader := r.Header.Get("Authorization")
        if authHeader == "" {
            http.Error(w, `{"error":"missing authorization header"}`, http.StatusUnauthorized)
            return
        }

        // 2. 检查格式：Bearer <token>
        parts := strings.SplitN(authHeader, " ", 2)
        if len(parts) != 2 || !strings.EqualFold(parts[0], "Bearer") {
            http.Error(w, `{"error":"invalid authorization format"}`, http.StatusUnauthorized)
            return
        }
        token := parts[1]

        // 3. 验证 Token（此处为示例，实际应调用验证服务）
        if !validateToken(token) {
            http.Error(w, `{"error":"invalid or expired token"}`, http.StatusUnauthorized)
            return
        }

        // 4. 将用户信息注入请求上下文（可选）
        // ctx := context.WithValue(r.Context(), "user_id", "12345")
        // r = r.WithContext(ctx)

        // 5. 通过验证，调用下一个 Handler
        next.ServeHTTP(w, r)
    })
}

// validateToken 模拟 Token 验证
func validateToken(token string) bool {
    // 实际项目中应验证 JWT 签名、过期时间、权限范围
    return token == "valid-token-12345"
}

注意： 上述 validateToken 仅为演示。生产环境中应使用 JWT 库（如 github.com/golang-jwt/jwt/v5）进行签名验证，并检查 exp（过期时间）、iss（签发者）等标准声明。

3.3.2 集成到 HTTP 服务

package main

import (
    "fmt"
    "net/http"
    "your-project/middleware"
)

func main() {
    // 定义受保护的路由
    protectedHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, `{"message":"welcome to protected resource"}`)
    })

    // 应用中间件
    http.Handle("/api/protected", middleware.AuthMiddleware(protectedHandler))

    // 公开路由，无需验证
    http.HandleFunc("/api/public", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, `{"message":"this is public"}`)
    })

    fmt.Println("Server starting on :8080")
    http.ListenAndServe(":8080", nil)
}

3.3.3 测试验证

测试场景	请求头	预期状态码	预期响应
无 Authorization 头	（无）	401	`{"error":"missing authorization header"}`
格式错误	`Authorization: Token abc`	401	`{"error":"invalid authorization format"}`
Token 无效	`Authorization: Bearer invalid-token`	401	`{"error":"invalid or expired token"}`
Token 有效	`Authorization: Bearer valid-token-12345`	200	`{"message":"welcome to protected resource"}`

3.4 中间件最佳实践与避坑指南

  关键原则：
  尽早返回：验证失败时直接写入响应并 return，避免调用 next
使用标准 HTTP 状态码：401 表示未认证，403 表示无权限
统一错误格式：返回 JSON 格式错误，便于客户端解析
避免在中间件中修改请求体：body 只能读取一次，如需读取请使用 io.NopCloser 重新包装
不要 panic：中间件应捕获 panic 并返回 500，而非让服务器崩溃

常见错误及解决方案：

错误模式	后果	正确做法
忘记 return 导致继续执行	双重写入响应，产生日志警告	在 `http.Error` 后立即 `return`
在中间件中修改请求 URL	路由匹配混乱	使用上下文传递参数，而非修改请求
中间件顺序错误	日志中间件无法记录认证失败	日志放最外层，认证放内层
硬编码 Token 验证逻辑	难以扩展和测试	抽象为 `TokenValidator` 接口

通过本章的学习，你已经掌握了 Go 标准库 HTTP 处理流程、中间件模式的核心思想，并亲手编写了第一个权限验证中间件。这是构建安全、可维护的 Go Web 服务的基础能力。