go标准库net/http足以构建轻量可靠的restful api；应使用http.servemux路由、统一路径风格、正确设置content-type与状态码、封装json响应、复用标准错误处理、全程传递context控制超时。
Go 标准库 net/http 足够支撑一个轻量、可靠、无依赖的 restful api，不需要框架也能清晰分层、正确处理状态码和内容协商。
用 http.ServeMux 做路由分发，别手写字符串匹配
手动解析 r.URL.Path 并用 if/else 匹配路径，容易漏掉尾部斜杠、大小写、URL 编码等边界情况，也难维护。直接用 http.ServeMux（或更明确地用 http.NewServeMux()）注册路径，它会自动处理前缀匹配和注册顺序。
常见错误：把 /users 和 /users/123 都注册成精确路径，结果后者 404；或者把 /users/ 注册了，但客户端请求 /users（无尾斜杠）失败。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 对资源集合用
/users（无尾斜杠），对单个资源用/users/{id}—— 这是 REST 约定，http.ServeMux不支持路径参数，所以得自己解析r.URL.Path的最后一段 - 注册
/users后，显式处理GET /users和POST /users在同一个 handler 里，用r.Method分支 - 避免注册
/users/（带斜杠），除非你真想把它当作子树入口；否则统一用不带斜杠的路径注册
json.Marshal 和 http.Error 是响应控制的核心
返回 JSON 时，别只写 w.Write([]byte(...))，必须设 Content-Type: application/json，否则前端可能解析失败；出错时别只写状态码，要用 http.Error 或手动设 w.WriteHeader + w.Header().Set，否则默认是 200。
常见错误：调用 json.NewEncoder(w).Encode(...) 后又调用 w.WriteHeader(400) —— 此时 header 已发送，状态码无效；或者忘记设 Content-Type，导致浏览器或 axios 按 text/html 解析 JSON 字符串。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 封装一个
writeJSON(w http.ResponseWriter, status int, v Interface{})函数，统一设 header、status、encode - 所有错误响应走
http.Error(w, msg, status)，它会自动设Content-Type: text/plain; charset=utf-8，适合调试；生产环境可换为结构化 JSON 错误 - 对 404、405 等标准错误，优先复用
http.NotFound、http.MethodNotAllowed，它们已预设好 header 和 body
用 context.Context 控制超时和取消，尤其在 DB 或 HTTP 调用时
HTTP handler 默认没有超时机制，一个卡住的数据库查询会让整个连接 hang 住，拖垮服务。Go 的 context 是唯一标准方式来传播取消信号和截止时间。
常见错误：在 handler 里启动 goroutine 但没传 context，导致超时后 goroutine 仍在运行；或用 time.AfterFunc 手动 cancel，绕过 context 生命周期管理。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 从
r.Context()派生子 context：ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)，并在 defer 中调用cancel() - 把
ctx传给数据库查询（如db.QueryContext(ctx, ...)）、下游 HTTP 请求（http.NewRequestWithContext(ctx, ...)）等支持 context 的接口 - 不要在 handler 中用
context.background()，它无法被父级 cancel，会破坏超时控制链
真正难的不是写出能跑的 API，而是让每个 handler 都一致地处理错误类型、状态码语义、context 传递和 JSON 序列化细节 —— 这些地方不抽象，项目长了就会出现 200 响应里塞错误信息、400 请求没返回 error 字段、超时请求还在写日志等隐性故障。