Golang net/http构建RESTful API教程

Go 的 net/http 包完全有能力构建生产级 RESTful API，但直接裸用 `http.HandleFunc` 会迅速陷入路径解析繁琐、JSON 处理重复、错误响应不一致、中间件难以复用等泥潭；本文直击痛点，对比剖析了原生 `ServeMux` 的局限，并力荐轻量灵活的 `gorilla/mux` 作为务实起点——它无缝兼容标准库、精准支持路径参数与自动 404，同时强调必须封装统一的 JSON 响应和错误处理函数，以保障代码一致性与可维护性，让开发者专注业务逻辑而非胶水代码。

Go 的 net/http 完全能写生产级 RESTful API，但别直接裸用 http.HandleFunc 拼路由——它不处理路径参数、不自动解析 JSON、不统一错误响应，硬刚只会让代码迅速失控。

为什么不能只用 http.HandleFunc 写 REST 接口

它只提供最底层的请求分发能力，所有 REST 约定都要手动实现：

• GET /users/123 中的 123 需要自己用 strings.Split(r.URL.Path, "/") 解析，易出错且不支持通配符
• POST /users 的 JSON 请求体要反复写 json.NewDecoder(r.Body).Decode(&u)，没校验、没超时控制
• 404、400、500 响应要手写 w.WriteHeader() + json.Marshal，状态码和结构体字段容易不一致
• 中间件（如日志、鉴权）无法复用，每个 handler 都得重复粘贴相同逻辑

用 http.ServeMux + 手动路由表是最小可行方案

比 HandleFunc 稍进一步，适合小项目或学习理解底层。关键点是：自己管理路由匹配逻辑，但复用 http.Handler 接口。

示例结构：

func main() {
	mux := http.NewServeMux()
	mux.Handle("/api/users", userHandler{}) // 实现 http.Handler
	mux.Handle("/api/users/", userHandler{}) // 注意末尾斜杠，匹配子路径
	http.ListenAndServe(":8080", mux)
}

type userHandler struct{}

func (h userHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	switch r.Method {
	case "GET":
		if id := strings.TrimPrefix(r.URL.Path, "/api/users/"); id != r.URL.Path {
			getUser(w, id) // 提取 ID 并处理
		} else {
			listUsers(w)
		}
	case "POST":
		createUser(w, r)
	default:
		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
	}
}

注意：http.ServeMux 本身不支持路径参数提取（如 /users/{id}），必须自己解析；"/api/users/" 这种带尾部斜杠的注册，才能匹配 /api/users/123 —— 不带斜杠则完全不匹配。

真正推荐的起点：加一层轻量路由库，比如 gorilla/mux

它保持 net/http 原生接口，零侵入，只解决路由痛点，不绑架你用它的中间件或上下文。

实操要点：

• 安装：go get -u github.com/gorilla/mux
• 注册带参数的路由：r := mux.NewRouter(); r.HandleFunc("/users/{id:[0-9]+}", getUser).Methods("GET")
• 提取参数：id := mux.Vars(r)["id"] —— 不用手撕字符串
• 自动 404：未注册的路径默认返回 404，不用每个 handler 判断
• 保留原生能力：仍可用 http.ListenAndServe，中间件也继续用 func(http.Handler) http.Handler 模式

一个典型 handler 示例：

func getUser(w http.ResponseWriter, r *http.Request) {
	id := mux.Vars(r)["id"]
	user, err := db.FindUserByID(id)
	if err != nil {
		http.Error(w, "User not found", http.StatusNotFound)
		return
	}
	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(user)
}

JSON 处理和错误响应必须封装成可复用函数

每次写 json.NewEncoder(w).Encode(...) 和 http.Error 很容易漏设 Content-Type 或错用状态码。建议在项目根目录建 response.go：

func JSON(w http.ResponseWriter, status int, v interface{}) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	json.NewEncoder(w).Encode(v)
}

func Error(w http.ResponseWriter, message string, status int) {
	JSON(w, status, map[string]string{"error": message})
}

然后所有 handler 统一调用：response.JSON(w, http.StatusOK, user)、response.Error(w, "invalid id", http.StatusBadRequest)。这样状态码、格式、头信息全部收敛，改起来也只改一处。

复杂点在于：如果业务需要返回结构化错误（如字段校验失败带具体字段名），这个简单封装就不够了——得定义自己的 ErrorResponse 类型，并在各 handler 中显式构造。很多人卡在这里，不是不会写，而是过早抽象，结果封装了一堆用不到的泛型和接口。先从上面那个 map[string]string 开始，等真有三个以上不同错误形态再重构。

好了，本文到此结束，带大家了解了《Golang net/http构建RESTful API教程》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多Golang知识！