Go 做 RESTful API，核心不是“怎么搭架子”，而是“怎么让 handler 不变成意大利面条”——路由、错误、序列化、状态码这四块没对齐，再漂亮的结构也扛不住一个 panic。
用 net/http 还是 gin？看错误处理能不能收口
别被“轻量”误导：net/http 默认不捕获 panic，一个未处理的空指针直接 500；gin 默认带 recovery 中间件，但默认错误响应体是 HTML，前端调用会卡在 JSON.parse() 报错。
如果团队熟悉中间件模型、需要统一鉴权/日志/限流，选 gin，但必须重写 gin.ErrorHandler，把 err.Error() 包进 {"error": "…", "code": 400} 结构里如果项目极简（比如内部配置服务），net/http 更透明：自己写个 http.HandlerFunc 包装器，统一 defer+recover+http.Error() 就够用echo 和 chi 也类似，关键看它的 HTTPErrorHandler 或 NotFoundHandler 能不能返回纯 JSON，而不是跳转或渲染模板
json.Marshal 出现 json: unsupported type: map[interface {}]interface{} 怎么办
这是 Go 的典型类型擦除陷阱：从 json.Unmarshal 直接读到 map[string]interface{} 是安全的，但反向用 map[interface{}]interface{}（比如某些 YAML 解析库输出）就炸了。
永远用 map[string]interface{} 接口做中间层，别信文档里写的 “generic map”如果必须处理动态 key，先用 reflect.ValueOf(v).MapKeys() 检查 key 类型，非 string 就提前报错，别等 json.Marshal 崩溃更稳的做法：定义 struct，哪怕字段是 json.RawMessage，用 json.Unmarshal 两次——第一次定结构，第二次解析子字段
REST 状态码写不对，前端永远在猜你什么意思
Go 的 http.Error() 默认塞 500，gin.C.String(200, …) 看似 OK，但漏掉 Content-Type: application/json，前端 fetch 会当成 text/plain。
立即学习“go语言免费学习笔记（深入）”；
201 Created 只用于 POST 成功且资源已生成（比如创建用户后返回 /users/123），别在 PUT 里乱用400 Bad Request 对应参数校验失败（id 不是数字、email 格式错），404 Not Found 只用于资源不存在（/users/999），别把业务错误（“余额不足”）塞进 404用 http.HandlerFunc 时，手动写 w.WriteHeader(400) + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(…)，三步缺一不可
gorilla/mux 路由里带可选参数，为什么 /api/v1/users/ 和 /api/v1/users 都 404
gorilla/mux 默认不自动处理尾部斜杠，Path("/users") 和 Path("/users/") 是两个路由，而多数前端发请求不带结尾 /，后端又习惯配 /users/。
加 StrictSlash(true)：访问 /users 会 301 重定向到 /users/，但移动端可能不跟重定向更实用的是用 Subrouter 分层：r.PathPrefix("/api/v1").Subrouter()，然后所有子路由统一不写开头 /，避免嵌套斜杠歧义如果用 gin，gin.SetMode(gin.ReleaseMode) 后它默认忽略尾部斜杠差异，但开发时关掉这个优化，不然上线才发现路由不一致
最常被跳过的其实是 Content-Type 头和 error body 的一致性——同一个 400 错误，有的 handler 返回 {"msg":"xxx"}，有的返回 {"error":"xxx"}，前端得写两套解析逻辑。这事没法靠框架解决，得在第一个 handler 里钉死格式。
评论(0)