如何使用Golang构建基础的REST API_Golang REST API接口设计与实现方法

net/http 可直接启动轻量 REST 服务：用 http.ListenAndServe 启动，http.HandleFunc 注册严格路径路由，handler 中需手动读取并校验 req.Body、设置 Content-Type 为 application/json；注意 req.Body 只能读一次、ServeMux 前缀匹配陷阱及显式处理 404。

用 net/http 启动最简 REST 服务，别急着上框架

Go 自带的 net/http 足够支撑大多数基础 API 场景，启动快、依赖少、逻辑透明。过度依赖 gin 或 echo 容易掩盖路由分发、中间件执行顺序、错误传播路径等关键细节。

• 直接调用 http.ListenAndServe(":8080", nil) 即可启动服务，nil 表示使用默认的 http.DefaultServeMux
• 用 http.HandleFunc("/users", handlerFunc) 注册路由，注意路径末尾不自动匹配子路径（/users ≠ /users/123）
• 所有 handler 函数签名必须是 func(http.ResponseWriter, *http.Request)，返回值不能传 error，需手动写入响应
• 别在 handler 里 panic——Go 的 HTTP server 不会 recover，一次 panic 就整条连接挂掉

解析 JSON 请求体时，json.Unmarshal 前必须先读取 req.Body

常见错误是直接对 req.Body 多次调用 json.Unmarshal，结果第二次开始全为零值。因为 req.Body 是单向流，读完即空。

• 务必用 io.ReadAll(req.Body) 一次性读出全部字节，再传给 json.Unmarshal
• 记得在读取前检查 req.Method 和 req.Header.Get("Content-Type")，避免对 GET 请求尝试读 body
• 若需复用 body（如日志或鉴权），应提前用 req.Body = io.NopCloser(bytes.NewBuffer(data)) 包装回 io.ReadCloser

data, err := io.ReadAll(req.Body)
if err != nil {
    http.Error(w, "bad request body", http.StatusBadRequest)
    return
}
var u User
if err := json.Unmarshal(data, &u); err != nil {
    http.Error(w, "invalid JSON", http.StatusBadRequest)
    return
}

返回 JSON 响应时，Content-Type 必须显式设置为 application/json; charset=utf-8

不设 header 导致前端 fetch().json() 报错 “Unexpected token”，浏览器可能按 text/html 解析，中文变乱码。

• 用 w.Header().Set("Content-Type", "application/json; charset=utf-8") 显式声明
• 避免用 fmt.Fprintf 直接输出 JSON 字符串——它不处理转义、不控制精度、不兼容结构体字段 tag（如 json:"name,omitempty"）
• 用 json.NewEncoder(w).Encode(v) 替代 json.Marshal + Write，前者支持流式编码，内存更友好

w.Header().Set("Content-Type", "application/json; charset=utf-8")
if err := json.NewEncoder(w).Encode(map[string]string{"status": "ok"}); err != nil {
    http.Error(w, "encode error", http.StatusInternalServerError)
}

路由设计要避开 http.ServeMux 的路径匹配陷阱

http.ServeMux 只做前缀匹配，且不区分 trailing slash，/api 会意外匹配到 /api/users 并交给同一 handler，但你没实现子路径逻辑。

• 注册路由时严格写全路径：http.HandleFunc("/api/users", listUsers)，不要只写 /api
• 需要层级路由，自己做路径分割：strings.Split(strings.TrimPrefix(req.URL.Path, "/api"), "/")
• 404 处理不能依赖框架自动 fallback——http.NotFound(w, req) 必须显式调用，否则返回空 200
• 如果 URL 含查询参数（如 /users?limit=10），用 req.URL.Query().Get("limit") 获取，别手撕 req.URL.RawQuery

真正卡住人的从来不是语法，而是 req.Body 只能读一次、http.ServeMux 不校验路径结尾、JSON 编码器和字符串拼接混用这些细节。写完一个 handler，先 curl 测一遍 status code 和 Content-Type，比跑通单元测试还管用。