选gin而非net/http：路由分组、中间件、JSON绑定开箱即用且性能不输；net/http仅适用于极简场景或协议层调试；务必设超时与优雅退出，结构体JSON字段需显式tag。
用 net/http 还是 gin？选型要看这三点
直接上生产环境别硬刚 net/http，除非你明确要极简、无依赖、或做协议层调试。日常开发中，gin 是更务实的选择：路由分组、中间件、JSON绑定、错误处理都开箱即用，且性能不输原生。
-
net/http适合写 CLI 工具的 HTTP 客户端、测试 mock 服务、或嵌入式轻量 endpoint（比如健康检查/health） -
gin的c.ShouldBindJSON(&v)自动处理空体、类型错、字段缺失，而net/http得自己调json.Decode+ 检查io.EOF和json.SyntaxError - 别用
echo或fiber除非团队已有约定——gin的文档、生态、IDE 支持最稳，go mod tidy后依赖干净，没隐藏的cgo或锁竞争风险
定义结构体时，JSON 字段名必须显式声明
Go 结构体字段默认不会被 JSON 序列化，除非首字母大写 + 显式加 json tag。漏掉 tag 是最常见 500 错误源头之一，尤其当字段名含下划线或想兼容前端驼峰命名时。
type User struct {
ID int `json:"id"`
UserName string `json:"user_name"` // 不写这行，前端收不到 user_name 字段
Email string `json:"email,omitempty"` // omitempty 在值为空时不输出该字段
}- 所有 API 响应结构体统一加
jsontag，别依赖默认行为 - 请求体（
POST /users）和响应体（GET /users/1）建议用不同结构体，避免omitempty干扰必填校验 - 时间字段用
time.Time没问题，但确保前端传的是 RFC3339 格式（如"2024-05-20T14:23:15Z"），否则ShouldBindJSON直接报错
启动服务前务必设置超时和优雅退出
不设超时的 http.Server 会卡住长连接，导致重启时连接堆积；不处理信号则 kill -15 后进程僵死，K8s readiness probe 失败。
srv := &http.Server{
Addr: ":8080",
Handler: router,
ReadTimeout: 10 * time.Second,
WriteTimeout: 30 * time.Second,
IdleTimeout: 60 * time.Second,
}
// 优雅退出
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
go func() {
<-quit
log.Println("shutting down server...")
if err := srv.Shutdown(context.Background()); err != nil {
log.Fatal("server shutdown error:", err)
}
}()
log.Println("server started on :8080")
log.Fatal(srv.ListenAndServe())
-
ReadTimeout防慢请求占满 worker，WriteTimeout防后端慢导致响应发不出 -
IdleTimeout必须设，否则 keep-alive 连接永久挂起，连接数持续上涨 - 别用
log.Fatal(srv.ListenAndServe())独立启动——它不响应信号，必须包一层srv.Shutdown()
路由分组 + 中间件 = 可维护性的起点
把 /api/v1/users 和 /health 混在同一个路由树里，等于给后续加鉴权、日志、限流埋雷。从第一天就用分组隔离关注点。
立即学习“go语言免费学习笔记（深入）”；
router := gin.Default()// 公共路由（无需鉴权） router.GET("/health", healthHandler)
// API 分组（带版本、可统一加中间件） v1 := router.Group("/api/v1") { v1.Use(authMiddleware(), loggingMiddleware()) v1.GET("/users", listUsers) v1.POST("/users", createUser) v1.GET("/users/:id", getUser) }
-
router.Group()返回新路由组，括号内是链式调用作用域，不是代码块作用域——变量依然可见 - 中间件函数必须以
c.Next()结尾，否则后续 handler 不执行；想中断就c.Abort()，比如鉴权失败时写c.JSON(401, gin.H{"error": "unauthorized"}) - 别在中间件里 recover panic——
gin.Default()已内置 recovery 中间件，重复 recover 会导致日志重复或 panic 被吞掉
复杂点在于中间件顺序：日志要最外层，鉴权紧贴业务 handler，而跨域（CORS）一般放最外层或紧挨路由组。这些顺序一旦写错，debug 成本远高于初期多花两分钟理清。
