Go语言搭建简单API：REST接口入门教程

本文深入浅出地讲解了如何仅用 Go 原生 net/http 包构建符合 REST 风格的轻量级 API 服务，摒弃框架依赖，直击核心实践要点：以资源为中心设计路径（如 /users）、严格按 HTTP 方法区分逻辑、显式设置语义化状态码、安全可靠地解析与校验 JSON 请求体、以及使用 json.NewEncoder 规范输出响应；同时通过精炼可运行的代码示例，揭示了初学者易踩的陷阱——如忽略方法检查、静默容忍空字段、误用 200 替代 404/400 等，并点明真实项目中紧随其后的关键挑战：中间件扩展、并发安全、路径参数提取与优雅关闭，让读者既掌握扎实基础，又看清进阶方向。

用 net/http 启一个最简 REST 服务

Go 原生 net/http 足够跑出符合 REST 风格的 API，不需要框架也能清晰表达资源语义。关键不是“能不能”，而是路由怎么映射、请求怎么解析、响应怎么组织。

核心是：用 http.HandleFunc 绑定路径和处理函数，再在函数里根据 req.Method 区分 GET/POST/PUT/DELETE；不要靠多个独立端口或 query 参数模拟动作。

• 所有路径应以资源为中心，比如 /users、/users/123
• 避免写成 /getUsers 或 /api?action=delete
• 处理函数必须显式检查 req.Method，否则容易忽略方法误用（比如用 GET 接收 JSON body）

解析 JSON 请求体并校验字段

Go 的 json.Unmarshal 默认对缺失字段静默容忍，直接解到 struct 可能导致空值被当成合法输入。REST 接口要求明确失败反馈，不能靠客户端猜。

常见错误是只做 err != nil 判断，却没检查结构体字段是否为空或越界。例如接收用户创建请求时，Name 和 Email 应为必填，但默认 struct 解码不会报错。

• 给字段加 json:"name,omitempty" 不解决必填问题，要用自定义校验逻辑
• 推荐先用 json.RawMessage 做预读，再按需解码——避免 panic 或静默丢数据
• 对 POST /users 这类创建接口，返回 400 Bad Request 并附具体错误字段比返回 500 更合理

返回标准 JSON 响应与状态码

REST 接口的响应不是“有 JSON 就行”，而要匹配 HTTP 状态码语义。比如 GET /users/999 找不到资源，该返回 404 Not Found，而不是 200 OK 加个 {"error": "not found"}。

Go 默认 http.ResponseWriter 的状态码是 200，不显式设置就永远 200。很多初学者漏掉这步，导致前端无法靠 status 判断流程分支。

• 用 w.WriteHeader(http.StatusNotFound) 显式设状态码，再写 body
• 统一响应结构推荐：包含 code（业务码）、message、data（可选），但不要和 HTTP status 冗余
• 别用 fmt.Fprintf(w, ...) 拼 JSON 字符串，用 json.NewEncoder(w).Encode(...) 防止格式错误和 XSS 风险

package main

import (
	"encoding/json"
	"log"
	"net/http"
)

type User struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
	Email string `json:"email"`
}

var users = map[int]User{
	1: {ID: 1, Name: "Alice", Email: "alice@example.com"},
}

func userHandler(w http.ResponseWriter, r *http.Request) {
	switch r.Method {
	case "GET":
		id := 1 // 简化示例，实际应从 URL path 提取
		if u, ok := users[id]; ok {
			w.Header().Set("Content-Type", "application/json")
			json.NewEncoder(w).Encode(u)
		} else {
			w.WriteHeader(http.StatusNotFound)
			json.NewEncoder(w).Encode(map[string]string{"error": "user not found"})
		}
	case "POST":
		var u User
		if err := json.NewDecoder(r.Body).Decode(&u); err != nil {
			w.WriteHeader(http.StatusBadRequest)
			json.NewEncoder(w).Encode(map[string]string{"error": "invalid JSON"})
			return
		}
		if u.Name == "" || u.Email == "" {
			w.WriteHeader(http.StatusBadRequest)
			json.NewEncoder(w).Encode(map[string]string{"error": "name and email required"})
			return
		}
		users[u.ID] = u
		w.WriteHeader(http.StatusCreated)
		json.NewEncoder(w).Encode(u)
	default:
		w.WriteHeader(http.StatusMethodNotAllowed)
		json.NewEncoder(w).Encode(map[string]string{"error": "method not allowed"})
	}
}

func main() {
	http.HandleFunc("/users", userHandler)
	log.Println("Server starting on :8080")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

真正难的不是写完这个例子，而是后续加中间件（日志、鉴权）、处理并发读写 map、支持路径参数（如 /users/{id}）、做 graceful shutdown —— 这些不写在基础例子里，但上线第一天就会撞上。

终于介绍完啦！小伙伴们，这篇关于《Go语言搭建简单API：REST接口入门教程》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布Golang相关知识，快来关注吧！