直接用 net/http 写 REST 接口易出错，因无方法区分、无路径参数解析、无 JSON 封装、无统一错误结构；gin 虽简化开发，但需手动设状态码、判空、处理 time.Time 序列化，并注意 :id 与 *path 差异及 Body 重放问题。
Go 做 RESTful API 不需要框架也能跑起来，但直接用 net/http 容易在路由设计、错误处理、JSON 序列化细节上翻车；用 gin 或 echo 能省力，但默认行为可能掩盖状态码、Content-Type 或中间件执行顺序问题。
为什么 http.HandleFunc 写 REST 接口容易出错
它不区分 HTTP 方法，也不解析路径参数，所有逻辑得手动判断。比如想支持 GET /users/123 和 DELETE /users/123，你得自己从 r.URL.Path 截字符串、从 r.Method 切分支、再手动校验 ID 格式——稍不留神就返回 200 给了 404 场景。
- 路径匹配靠字符串操作，
/users/123/和/users/123被当成两个路由 - 没有内置 JSON 响应封装，
json.Marshal失败时容易 panic 或静默丢数据 - 无法统一设置
Content-Type: application/json，前端可能收不到正确类型头 - 错误响应没标准结构，比如 400 错误该返回什么字段、是否带
message、是否含code
gin 中如何正确返回 REST 风格的 JSON 响应
gin 的 c.JSON() 看似简单，但默认不设状态码（始终是 200），也不拦截 nil 结构体导致空对象 {} 返回，更不会自动处理 time.Time 序列化格式。
- 显式调用
c.JSON(http.StatusCreated, data)，别依赖默认 200 - 对可能为
nil的结构体，先判空再响应，避免前端收到{}却以为成功 - 全局注册
json.Marshal替换：用jsoniter.ConfigCompatibleWithStandardLibrary支持time.Time输出 RFC3339 - 不要在 handler 里直接
log.Fatal，会 kill 整个 server；改用c.AbortWithStatusJSON(http.StatusInternalServerError, errResp)
REST 路由设计中 :id 和 *path 的实际区别
写 GET /api/v1/users/:id 是常规做法，但如果你用 GET /api/v1/users/:id/*path，*path 会捕获剩余路径（如 /profile/avatar），而 :id 只取第一个段。这在做代理或嵌套路由时有用，但多数 REST 场景下反而让路由表难维护、测试难覆盖。
立即学习“go语言免费学习笔记（深入）”；
-
:id是命名参数，值通过c.Param("id")取，注意它永远是字符串，需手动转int并检查错误 -
*path是通配参数，值含前导/，比如请求/users/123/logs时，c.Param("*path")是/logs - 别把
:id当校验用——/users/abc也会被匹配，必须在 handler 里验证strconv.Atoi是否报错 - 版本号建议放在 URL 路径（
/v1/）而非 Header，方便 CDN 缓存和日志归类
中间件里读取请求 Body 后，handler 拿不到数据怎么办
http.Request.Body 是单次读取流，中间件调了 ioutil.ReadAll 或 json.Decode 后，后续 handler 再读就是空。这是 Go HTTP 最常被忽略的底层细节。
- 用
c.Request.Body = io.NopCloser(bytes.NewBuffer(bodyBytes))把读过的 body 重装回去 - 更稳妥的做法：中间件只读必要字段（如 token 在 Authorization header），避免提前消费 Body
- 如果必须解析 Body（如做签名验证），建议用自定义
io.ReadCloser实现可重放逻辑，而不是临时 buffer - 别依赖
c.CopyBody这类非标准方法——gin本身没提供，是某些第三方扩展加的，升级时容易断裂
真正卡住人的从来不是“怎么写个 GET 接口”，而是 401 时该不该返回 WWW-Authenticate 头、PUT 和 PATCH 对空字段的语义差异、或者并发写同一个 struct 导致 JSON 输出字段乱序——这些细节不会出现在“教程”里，但上线后立刻暴露。
