4. 路由与中间件：使用标准库与流行路由库对比、中间件模式介绍

在构建 Go REST API 时，路由（Router）与中间件（Middleware）构成了服务边界的核心骨架。路由决定了请求如何被分发到对应的处理函数，而中间件则提供了在请求处理前后执行通用逻辑的能力。本章将深入对比 Go 标准库 net/http 与流行路由库 gorilla/mux、chi 的差异，并系统介绍中间件模式的设计与实现。

4.1 路由库核心能力对比

Go 1.22 版本对标准库 net/http 的路由能力进行了显著增强，引入了路径参数和方法匹配。然而，在复杂 REST API 场景下，第三方路由库仍然提供了更丰富的特性。下表从多个维度对比三种路由方案：

特性维度 net/http (Go 1.22+) gorilla/mux chi
路径参数 支持 {param} 语法 支持 {param} 与正则约束 支持 {param} 与正则约束
HTTP 方法匹配 原生支持 GET /path 写法 通过 .Methods() 链式调用 通过 .Method() 或路由分组
子路由/分组 需手动组合 http.Handler 通过 .PathPrefix() + .Subrouter() 原生 .Route() 与 .Group()
中间件链 需手动嵌套 http.Handler 通过 .Use() 方法 通过 .Use() 方法，支持分组中间件
上下文传值 使用 context.WithValue 内置 mux.Vars() 提取参数 内置 chi.URLParam() 提取参数
性能 中等（标准库实现） 中等（基于 map 匹配） 高（基于基数树实现）
社区生态 官方维护，无额外依赖 成熟稳定，文档丰富 轻量现代，与 net/http 兼容性好
选型建议： 对于新项目，推荐优先考虑 chi，它在保持与标准库高度兼容的同时，提供了更优的性能和更灵活的中间件管理。如果团队对标准库有强依赖且 Go 版本 ≥ 1.22，可直接使用 net/http 内置路由。遗留项目或需要复杂正则匹配时，gorilla/mux 仍是可靠选择。

4.2 路由实现示例对比

以下通过一个简单的用户资源 REST API 示例，展示三种路由方案的具体实现差异。

4.2.1 使用标准库 net/http (Go 1.22+)

package main

import (
    "encoding/json"
    "net/http"
)

type User struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}

func getUser(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")
    // 模拟查询用户
    user := User{ID: id, Name: "Alice"}
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(user)
}

func createUser(w http.ResponseWriter, r *http.Request) {
    var user User
    if err := json.NewDecoder(r.Body).Decode(&user); err != nil {
        http.Error(w, "Invalid request body", http.StatusBadRequest)
        return
    }
    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(user)
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /users/{id}", getUser)
    mux.HandleFunc("POST /users", createUser)
    http.ListenAndServe(":8080", mux)
}

4.2.2 使用 chi 路由库

package main

import (
    "encoding/json"
    "net/http"

    "github.com/go-chi/chi/v5"
)

func getUser(w http.ResponseWriter, r *http.Request) {
    id := chi.URLParam(r, "id")
    user := User{ID: id, Name: "Bob"}
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(user)
}

func createUser(w http.ResponseWriter, r *http.Request) {
    var user User
    if err := json.NewDecoder(r.Body).Decode(&user); err != nil {
        http.Error(w, "Invalid request body", http.StatusBadRequest)
        return
    }
    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(user)
}

func main() {
    r := chi.NewRouter()
    r.Get("/users/{id}", getUser)
    r.Post("/users", createUser)
    http.ListenAndServe(":8080", r)
}
关键差异： chi 使用 chi.URLParam() 提取路径参数，而标准库使用 r.PathValue()。chi 的链式调用 .Get()、.Post() 更简洁，且天然支持中间件注入。

4.3 中间件模式详解

中间件是一种在请求处理管道中插入通用逻辑的设计模式。在 Go 中，中间件本质上是一个接收 http.Handler 并返回 http.Handler 的函数。这种模式允许开发者将日志记录、认证、限流、错误恢复等横切关注点与业务逻辑解耦。

4.3.1 中间件的标准签名

type Middleware func(http.Handler) http.Handler

一个典型的中间件实现包含三个步骤：

  1. 在请求处理前执行前置逻辑（如记录开始时间）
  2. 调用 next.ServeHTTP(w, r) 将控制权传递给下一个处理器
  3. 在请求处理后执行后置逻辑（如计算耗时）

4.3.2 日志中间件实现示例

func loggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        // 前置处理：记录请求信息
        log.Printf("Started %s %s", r.Method, r.URL.Path)
        
        // 调用下一个处理器
        next.ServeHTTP(w, r)
        
        // 后置处理：记录耗时
        log.Printf("Completed %s in %v", r.URL.Path, time.Since(start))
    })
}

4.4 中间件执行流程与架构

下图展示了多个中间件在请求处理管道中的执行顺序。每个中间件包裹下一个处理器，形成洋葱模型：

中间件洋葱模型执行流程 请求 日志中间件 认证中间件 限流中间件 业务处理器 响应 每个中间件在调用 next.ServeHTTP() 之前执行前置逻辑， 调用之后执行后置逻辑，形成请求/响应的双向处理管道 中间件执行顺序 1. 请求进入 → 日志中间件（前置）→ 认证中间件（前置）→ 限流中间件（前置） 2. 到达业务处理器，执行核心逻辑 3. 响应返回 → 限流中间件（后置）→ 认证中间件（后置）→ 日志中间件（后置） 4. 最终响应返回客户端

4.5 中间件在路由库中的集成

不同路由库对中间件的集成方式略有差异，但核心思想一致。以下展示在 chi 中如何组织中间件链：

func main() {
    r := chi.NewRouter()
    
    // 全局中间件：应用于所有路由
    r.Use(middleware.Logger)    // chi 内置日志中间件
    r.Use(middleware.Recoverer) // 异常恢复中间件
    r.Use(middleware.Timeout(30 * time.Second)) // 超时控制
    
    // 路由分组：为特定资源组添加中间件
    r.Route("/api/v1/users", func(r chi.Router) {
        // 仅 /api/v1/users 下的路由需要认证
        r.Use(authMiddleware)
        
        r.Get("/", listUsers)
        r.Get("/{id}", getUser)
        r.Post("/", createUser)
        r.Put("/{id}", updateUser)
        r.Delete("/{id}", deleteUser)
    })
    
    // 公开路由：不需要认证
    r.Get("/health", healthCheck)
    
    http.ListenAndServe(":8080", r)
}
中间件顺序陷阱： 中间件的注册顺序决定了执行顺序。如果认证中间件在日志中间件之前注册，那么认证失败时日志中间件将不会记录该请求。通常建议将日志、恢复、超时等基础设施中间件放在最外层，将认证、鉴权等业务中间件放在内层。

4.6 自定义中间件的最佳实践

编写高质量中间件时，应遵循以下原则：

  • 单一职责：每个中间件只关注一个横切关注点，避免在一个中间件中混合日志、认证、限流等逻辑。
  • 上下文传递：使用 context.WithValue 在中间件之间传递数据（如用户信息、请求ID），避免使用全局变量。
  • 错误处理：中间件应捕获 panic 并返回 500 错误，避免服务崩溃。
  • 可测试性：中间件应接受 http.Handler 作为参数，便于单元测试时注入 mock 处理器。
// 上下文键类型，避免冲突
type contextKey string

const UserIDKey contextKey = "userID"

// 认证中间件：从 Token 提取用户信息并注入上下文
func authMiddleware(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, "Missing authorization token", http.StatusUnauthorized)
            return
        }
        // 模拟 Token 解析
        userID := extractUserIDFromToken(token)
        if userID == "" {
            http.Error(w, "Invalid token", http.StatusUnauthorized)
            return
        }
        // 将用户 ID 注入上下文
        ctx := context.WithValue(r.Context(), UserIDKey, userID)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

4.7 路由与中间件的架构决策

下图展示了在 REST API 服务中，路由与中间件的整体架构关系：

REST API 路由与中间件架构 客户端 全局中间件层 日志 恢复 超时控制 请求ID 路由分发器 路径匹配 方法匹配 参数提取 分组中间件层 认证 鉴权 限流 数据校验 业务处理器 响应 请求依次经过全局中间件 → 路由分发 → 分组中间件 → 业务处理器 响应沿原路径反向返回，每个中间件可对请求和响应进行双向处理

4.8 本章小结

路由与中间件是 Go REST API 服务边界的核心基础设施。标准库 net/http 在 Go 1.22+ 中已具备基本的路由能力，适合简单场景；gorilla/mux 提供丰富的匹配规则，适合遗留项目；chi 则在性能、灵活性和与现代 Go 生态的兼容性上表现最佳，是新建项目的首选。中间件模式通过洋葱模型实现了横切关注点的优雅分离，合理组织中间件顺序和层级是构建健壮 API 服务的关键。

← 上一章 📖 返回目录 下一章 →