Golang搭建简易API服务教程

来到golang学习网的大家，相信都是编程学习爱好者，希望在这里学习Golang相关编程知识。下面本篇文章就来带大家聊聊《Golang搭建简单API服务教程》，介绍一下，希望对大家的知识积累有所帮助，助力实战开发！

最常见原因是监听地址写成了"localhost:8080"或"127.0.0.1:8080"，应改用":8080"监听所有接口；此外需检查端口占用、Docker映射、路由前缀匹配逻辑、JSON解析时机及生产环境应使用http.Server而非ListenAndServe。

为什么 http.ListenAndServe 启动后没报错却访问不了？

最常见原因是监听地址写成了 "localhost:8080" 或 "127.0.0.1:8080"，导致外部网络（包括 Docker 容器外、云服务器安全组外）无法连接。Go 的 net/http 默认只绑定到本地回环地址。

• 对外提供服务时，必须用 ":8080"（空主机名），表示监听所有可用网络接口
• 若端口被占用，http.ListenAndServe 会返回 "address already in use" 错误；但若监听成功却无响应，优先检查绑定地址
• 在 Docker 中运行时，还要确认 EXPOSE 和宿主机 -p 映射是否匹配

如何用 http.ServeMux 实现路径路由？

http.ServeMux 是 Go 标准库默认的 HTTP 路由器，支持前缀匹配而非完全匹配，这点容易引发意料外的行为。

• "/api" 会匹配 /api、/api/users、甚至 /apixxx —— 因为它只是字符串前缀判断
• 要精确匹配，需手动检查 r.URL.Path，或改用第三方路由器（如 gorilla/mux、chi）
• 注册顺序有影响：后注册的 handler 若前缀覆盖了前面的，可能“吃掉”本该由更具体规则处理的请求

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(http.StatusOK)
		w.Write([]byte("ok"))
	})
	// 注意：这个会匹配 /api 和 /api/xxx，但不会匹配 /apiuser
	mux.HandleFunc("/api/", func(w http.ResponseWriter, r *http.Request) {
		if r.URL.Path == "/api/" {
			http.Error(w, "use subpath", http.StatusBadRequest)
			return
		}
		w.Write([]byte("data"))
	})
	http.ListenAndServe(":8080", mux)
}

怎么读取 JSON 请求体并避免 i/o timeout 或 invalid character？

直接调用 json.Decode(r.Body) 前，必须确保 r.Body 没被其他逻辑提前读取（比如日志中间件调用了 r.Body.Read 或 io.ReadAll），否则后续解码会得到空内容或 EOF。

• 务必在 handler 开头就处理请求体，不要依赖中间件自动解析
• 设置 r.Header.Get("Content-Type") 检查是否为 "application/json"，避免非 JSON 请求触发解析错误
• 使用 json.NewDecoder 而非 json.Unmarshal 可减少内存拷贝，但两者都要求 body 可读一次
• 超时通常来自客户端未发送完整 body，或服务端未设 http.Server.ReadTimeout

type User struct {
	Name string `json:"name"`
	Age  int    `json:"age"`
}

func createUser(w http.ResponseWriter, r *http.Request) {
	if r.Method != "POST" {
		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
		return
	}
	if r.Header.Get("Content-Type") != "application/json" {
		http.Error(w, "content-type must be application/json", http.StatusBadRequest)
		return
	}

	var u User
	decoder := json.NewDecoder(r.Body)
	if err := decoder.Decode(&u); err != nil {
		http.Error(w, "invalid json: "+err.Error(), http.StatusBadRequest)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(map[string]string{"status": "created"})
}

为什么生产环境不建议直接用 http.ListenAndServe？

标准 http.ListenAndServe 启动的 server 缺少对优雅关闭、超时控制、连接限制等关键生产特性的配置能力。一旦进程收到 SIGINT/SIGTERM，它会立即退出，正在处理的请求可能被中断。

• 必须用 http.Server 结构体显式构造，并设置 ReadTimeout、WriteTimeout、IdleTimeout
• 关闭时需调用 srv.Shutdown()，配合 context.WithTimeout 等待活跃连接完成
• 日志、panic 恢复、CORS、gzip 压缩等都需要自己封装中间件，标准库只提供最基础骨架

真正上线时，http.ListenAndServe 只适合原型验证——它掩盖了连接生命周期管理的复杂性。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~