Golang开发RESTful接口教程

Go标准库net/http可写生产级RESTful API，但需用chi或gorilla/mux替代ServeMux以支持路径参数、方法限制；REST路由须遵循资源命名、HTTP方法语义；JSON处理需手动读取Body、导出结构体字段并设Content-Type；错误须按4xx/5xx/404分类返回状态码，统一错误格式与中间件。

Go 标准库 net/http 足够写生产级 RESTful API，但直接裸用容易陷入路由混乱、错误处理不一致、中间件缺失等问题；真正关键不是“能不能”，而是“怎么组织才不容易翻车”。

用 http.ServeMux 还是选第三方路由器？

标准 http.ServeMux 只支持前缀匹配（如 /api/users 会误匹配 /api/users/123/delete），不支持路径参数（如 /users/{id}）、方法限制或嵌套路由。实际项目中几乎没人裸用它。

推荐直接上轻量但可靠的 gorilla/mux 或 chi：

• chi 更现代，中间件链清晰，对 context.Context 支持原生，适合需要鉴权、日志、超时控制的场景
• gorilla/mux 文档全、生态稳，兼容性更好，老项目迁移成本低
• 别碰 gin 或 echo 除非你明确需要它们的“便利语法糖”——它们隐藏了 http.Handler 底层，调试中间件顺序或自定义响应头时反而更难定位问题

RESTful 路由设计要避开的三个硬伤

所谓“RESTful”不是把 URL 写成 /get_user?id=123 就算数。常见反模式：

• 用动词命名资源路径：POST /api/users/create → 应该是 POST /api/users
• 在 URL 里塞动作状态：GET /api/orders/cancelled → 应该是 GET /api/orders?status=cancelled
• 忽略 HTTP 方法语义：用 GET 做删操作（导致缓存、代理重放等风险）

一个典型用户管理路由示例（chi）：

router.Post("/users", createUserHandler)
router.Get("/users/{id}", getUserHandler)
router.Put("/users/{id}", updateUserHandler)
router.Delete("/users/{id}", deleteUserHandler)

注意：{id} 是路径参数，不是字符串拼接——解析交给路由器，别自己 strings.Split(r.URL.Path, "/")。

JSON 请求/响应处理必须手动做三件事

Go 不像 Node.js 或 Python 那样自动序列化/反序列化请求体。漏掉任一环节就会返回空对象或 400 错误：

• 请求体必须用 r.Body 读取一次且仅一次（多次读会 EOF）；建议用 io.ReadAll + json.Unmarshal
• 结构体字段必须导出（首字母大写），且加 json: tag 显式声明键名，比如 UserName string `json:"user_name"`
• 响应务必设置 Content-Type: application/json; charset=utf-8，否则前端可能解析失败（尤其 IE 或某些安卓 WebView）

示例响应写法：

w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(http.StatusOK)
json.NewEncoder(w).Encode(map[string]interface{}{"id": 123, "name": "Alice"})

错误处理不能只靠 log.Fatal 或 panic

HTTP 错误必须转成对应状态码返回，而不是打印日志后挂掉整个服务。常见错误类型和处理方式：

• 客户端错误（4xx）：参数校验失败、ID 格式不对、缺少必要字段 → 返回 http.StatusBadRequest 或 http.StatusUnprocessableEntity，附带错误详情 JSON
• 服务端错误（5xx）：数据库连不上、第三方 API 超时 → 返回 http.StatusInternalServerError，但日志里记全栈信息，响应体只返回泛化提示（如 {"error": "internal error"}）
• 资源不存在（404）：别用 nil 判断就返回 200 + 空对象，要用 http.StatusNotFound

别在 handler 里写重复的 if err != nil { ... }，抽成统一的 errorHandler 中间件或封装 writeJSONError 工具函数。

真正难的不是写通一个接口，而是让所有接口共享同一套错误格式、日志上下文、超时控制和取消信号传递——这些细节堆起来，才是 Web API 可维护性的分水岭。