Go语言如何实现Per-Handler中间件并传递请求上下文数据

在Go语言的Web开发场景中，全局中间件往往会对所有路由生效，当我们需要为某个特定路由单独添加日志、鉴权或者数据预处理逻辑时，Per-Handler中间件就是更合适的选择。同时请求上下文数据传递能让中间件和处理函数之间共享自定义信息，减少参数冗余。接下来我们详细讲解这两种技术的实现方式。

Per-Handler中间件的核心思路

Per-Handler中间件的本质是接收一个处理函数作为参数，返回一个包装后的新处理函数，在新函数的逻辑中先执行中间件的自定义逻辑，再调用原始处理函数。这种设计不会侵入原有处理函数的逻辑，还能灵活组合多个中间件。

我们首先定义一个处理函数类型，统一Web处理函数的签名：

package main

import (
	"net/http"
)

// 定义处理函数类型，和http.HandlerFunc保持一致
type Handler func(http.ResponseWriter, *http.Request)

实现单个Per-Handler中间件

以日志中间件为例，它会在处理请求前打印请求路径，处理完成后打印请求耗时：

// 日志中间件，接收原始处理函数，返回包装后的处理函数
func LoggerMiddleware(next Handler) Handler {
	return func(w http.ResponseWriter, r *http.Request) {
		// 前置逻辑：打印请求路径
		println("收到请求，路径：", r.URL.Path)
		// 调用原始处理函数
		next(w, r)
		// 后置逻辑：这里可以补充耗时统计等逻辑
		println("请求处理完成，路径：", r.URL.Path)
	}
}

为单个路由绑定Per-Handler中间件

在使用net/http注册路由时，我们可以直接将中间件和处理函数组合后注册：

func main() {
	// 定义原始处理函数
	helloHandler := func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("hello world"))
	}
	// 为hello路由单独绑定Logger中间件，不需要全局注册
	http.HandleFunc("/hello", LoggerMiddleware(helloHandler))
	http.ListenAndServe(":8080", nil)
}

这样只有访问/hello路由时才会触发日志中间件，其他路由不会受影响，实现了Per-Handler的效果。

请求上下文数据传递的实现

Go语言的context包可以在请求生命周期内传递自定义数据，我们可以在中间件中往context里写入数据，在处理函数中读取这些数据，不需要修改处理函数的参数列表。

上下文数据的写入与读取

首先定义一个上下文key类型，避免不同包之间的key冲突：

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

// 定义用户ID的上下文key
const UserIDKey contextKey = "user_id"

然后在鉴权中间件中写入用户ID到上下文：

// 鉴权中间件，验证请求头中的token，写入用户ID到上下文
func AuthMiddleware(next Handler) Handler {
	return func(w http.ResponseWriter, r *http.Request) {
		// 获取请求头中的token
		token := r.Header.Get("token")
		if token == "" {
			http.Error(w, "缺少token", http.StatusUnauthorized)
			return
		}
		// 这里模拟token验证，实际场景需要调用验证逻辑
		if token != "valid_token" {
			http.Error(w, "token无效", http.StatusUnauthorized)
			return
		}
		// 模拟获取用户ID
		userID := "10001"
		// 将用户ID写入上下文，生成新的request
		ctx := context.WithValue(r.Context(), UserIDKey, userID)
		newReq := r.WithContext(ctx)
		// 传递新的request给下一个处理函数
		next(w, newReq)
	}
}

在处理函数中读取上下文的用户ID：

// 用户处理函数，从上下文读取用户ID
func UserHandler(w http.ResponseWriter, r *http.Request) {
	// 从上下文读取用户ID
	userID := r.Context().Value(UserIDKey)
	if userID == nil {
		http.Error(w, "未获取到用户ID", http.StatusInternalServerError)
		return
	}
	// 类型断言获取字符串类型的用户ID
	id, ok := userID.(string)
	if !ok {
		http.Error(w, "用户ID类型错误", http.StatusInternalServerError)
		return
	}
	w.Write([]byte("当前用户ID：" + id))
}

组合多个Per-Handler中间件

我们可以将多个中间件和处理函数组合，实现逻辑复用：

func main() {
	// 组合鉴权中间件和日志中间件，再绑定到处理函数
	handler := LoggerMiddleware(AuthMiddleware(UserHandler))
	http.HandleFunc("/user", handler)
	http.ListenAndServe(":8080", nil)
}

注意事项

• context的key建议使用自定义类型，不要直接使用字符串或者基本类型，避免不同包之间的key冲突
• 上下文数据只在当前请求的生命周期内有效，不要存储长生命周期的数据
• 中间件中如果提前返回响应，不要忘记调用return，避免后续逻辑继续执行
• Per-Handler中间件的组合顺序会影响执行顺序，先写的中间件会先执行前置逻辑，后执行后置逻辑

通过Per-Handler中间件和请求上下文数据传递的结合，我们可以灵活地为单个路由定制处理逻辑，同时在不同的处理阶段共享请求相关的数据，让代码结构更清晰，可维护性更高。

Gomiddlewarecontextrequest_contextPer_Handler修改时间：2026-06-16 06:45:35