4、路由与请求分发：使用 gorilla/mux 或 chi 实现路由、路径参数提取、请求上下文传递

在微服务网关中，路由与请求分发是请求进入系统的第一道关卡。Go 生态中 gorilla/mux 和 chi 是两款最成熟的路由库，它们不仅支持标准的 HTTP 方法匹配，还提供了路径参数提取、中间件链、请求上下文传递等网关必备能力。本章将围绕这两款库的核心用法，结合权限审计网关的实际场景，讲解路由设计、参数提取与上下文传递的最佳实践。

4.1 路由库选型对比

在开始编码前，先明确 gorilla/mux 与 chi 的差异，以便根据项目需求做出选择。

4.2 路由注册与路径参数提取

网关的核心职责之一是根据请求路径将流量分发到对应的处理函数。以下分别展示两种库的典型用法。

4.2.1 使用 gorilla/mux

package main

import (
    "encoding/json"
    "log"
    "net/http"
    "github.com/gorilla/mux"
)

func main() {
    r := mux.NewRouter()

    // 静态路由
    r.HandleFunc("/health", healthHandler).Methods("GET")

    // 路径参数：{tenant} 和 {service}
    r.HandleFunc("/api/v1/{tenant}/services/{service}", serviceHandler).Methods("GET")

    // 带正则约束的路径参数
    r.HandleFunc("/api/v1/{tenant:[a-z0-9]+}/audit/{id:[0-9]+}", auditHandler).Methods("GET")

    log.Fatal(http.ListenAndServe(":8080", r))
}

func serviceHandler(w http.ResponseWriter, r *http.Request) {
    vars := mux.Vars(r)
    tenant := vars["tenant"]
    service := vars["service"]
    w.Write([]byte("Tenant: " + tenant + ", Service: " + service))
}

func auditHandler(w http.ResponseWriter, r *http.Request) {
    vars := mux.Vars(r)
    id := vars["id"]
    w.Write([]byte("Audit ID: " + id))
}

func healthHandler(w http.ResponseWriter, r *http.Request) {
    json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
}

4.2.2 使用 chi

package main

import (
    "encoding/json"
    "log"
    "net/http"
    "github.com/go-chi/chi/v5"
)

func main() {
    r := chi.NewRouter()

    // 静态路由
    r.Get("/health", healthHandler)

    // 路径参数
    r.Get("/api/v1/{tenant}/services/{service}", serviceHandler)

    // 带正则约束
    r.Get("/api/v1/{tenant:[a-z0-9]+}/audit/{id:[0-9]+}", auditHandler)

    log.Fatal(http.ListenAndServe(":8080", r))
}

func serviceHandler(w http.ResponseWriter, r *http.Request) {
    tenant := chi.URLParam(r, "tenant")
    service := chi.URLParam(r, "service")
    w.Write([]byte("Tenant: " + tenant + ", Service: " + service))
}

func auditHandler(w http.ResponseWriter, r *http.Request) {
    id := chi.URLParam(r, "id")
    w.Write([]byte("Audit ID: " + id))
}

func healthHandler(w http.ResponseWriter, r *http.Request) {
    json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
}

4.3 请求上下文传递

在网关中，请求上下文（context）是贯穿整个请求生命周期的核心载体。路由库需要将路径参数、认证信息、审计 ID 等数据注入到 context.Context 中，供后续中间件和处理函数使用。

4.3.1 chi 的原生上下文注入

chi 内置了上下文中间件，自动将路径参数注入到请求上下文中。开发者还可以通过自定义中间件注入更多数据。

func main() {
    r := chi.NewRouter()

    // 全局中间件：注入请求 ID
    r.Use(requestIDMiddleware)

    // 路由分组：注入租户上下文
    r.Route("/api/v1/{tenant}", func(r chi.Router) {
        r.Use(tenantContextMiddleware)
        r.Get("/services/{service}", serviceHandler)
    })

    log.Fatal(http.ListenAndServe(":8080", r))
}

func requestIDMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ctx := context.WithValue(r.Context(), "request_id", uuid.New().String())
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

func tenantContextMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        tenant := chi.URLParam(r, "tenant")
        ctx := context.WithValue(r.Context(), "tenant", tenant)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

func serviceHandler(w http.ResponseWriter, r *http.Request) {
    requestID := r.Context().Value("request_id").(string)
    tenant := r.Context().Value("tenant").(string)
    service := chi.URLParam(r, "service")
    w.Write([]byte("RequestID: " + requestID + ", Tenant: " + tenant + ", Service: " + service))
}

4.3.2 gorilla/mux 的上下文传递

gorilla/mux 不自动注入上下文，需要开发者手动将路径参数写入 context。

func main() {
    r := mux.NewRouter()
    r.Use(requestIDMiddleware)
    r.HandleFunc("/api/v1/{tenant}/services/{service}", serviceHandler).Methods("GET")
    log.Fatal(http.ListenAndServe(":8080", r))
}

func requestIDMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ctx := context.WithValue(r.Context(), "request_id", uuid.New().String())
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

func serviceHandler(w http.ResponseWriter, r *http.Request) {
    vars := mux.Vars(r)
    ctx := r.Context()
    // 手动将路径参数注入上下文
    ctx = context.WithValue(ctx, "tenant", vars["tenant"])
    ctx = context.WithValue(ctx, "service", vars["service"])
    r = r.WithContext(ctx)

    requestID := ctx.Value("request_id").(string)
    tenant := ctx.Value("tenant").(string)
    w.Write([]byte("RequestID: " + requestID + ", Tenant: " + tenant))
}

4.4 路由分组与中间件作用域

权限审计网关通常需要按功能模块划分路由，例如：认证路由不需要审计中间件，而审计路由需要认证和审计双重中间件。chi 的路由分组机制可以精确控制中间件的作用域。

func main() {
    r := chi.NewRouter()

    // 全局中间件：日志、恢复
    r.Use(middleware.Logger)
    r.Use(middleware.Recoverer)

    // 公开路由组：不需要认证
    r.Group(func(r chi.Router) {
        r.Post("/auth/login", loginHandler)
        r.Post("/auth/register", registerHandler)
    })

    // 受保护路由组：需要认证和审计
    r.Group(func(r chi.Router) {
        r.Use(authMiddleware)
        r.Use(auditMiddleware)

        r.Get("/api/v1/{tenant}/services", listServicesHandler)
        r.Post("/api/v1/{tenant}/services", createServiceHandler)
        r.Delete("/api/v1/{tenant}/services/{id}", deleteServiceHandler)
    })

    log.Fatal(http.ListenAndServe(":8080", r))
}

4.5 路由分发流程架构

下图展示了请求从进入网关到被处理函数响应的完整路由分发流程，重点体现路径参数提取和上下文传递的环节。

4.6 路径参数提取的常见陷阱

在实际开发中，路径参数提取看似简单，但容易踩坑。以下列出三个高频问题及解决方案。

4.7 路由设计最佳实践

结合权限审计网关的领域边界，总结以下路由设计原则：

• 版本化路由： 所有 API 以 /api/v1/ 开头，便于后续版本升级。
• 租户隔离： 将租户 ID 作为路径参数，如 /api/v1/{tenant}/audit，确保多租户数据隔离。
• 资源嵌套： 使用嵌套路由表达资源层级，如 /api/v1/{tenant}/services/{service}/audit。
• 中间件分层： 全局中间件 → 分组中间件 → 路由级中间件，避免中间件污染无关路由。
• 上下文类型安全： 定义自定义类型作为 context key，避免字符串 key 冲突。

// 自定义上下文 key 类型，避免冲突
type contextKey string

const (
    ContextKeyTenant    contextKey = "tenant"
    ContextKeyUserID    contextKey = "user_id"
    ContextKeyRequestID contextKey = "request_id"
)

// 使用示例
func tenantFromContext(ctx context.Context) string {
    if v, ok := ctx.Value(ContextKeyTenant).(string); ok {
        return v
    }
    return ""
}